1/* 2 * Copyright 2011 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * Ingo Weinhold, bonefish@users.sf.net 8 * 9 * Corresponds to: 10 * headers/os/storage/AppFileInfo.h rev 42274 11 * src/kits/storage/AppFileInfo.cpp rev 42274 12 */ 13 14 15/*! 16 \file AppFileInfo.h 17 \ingroup storage 18 \ingroup libbe 19 \brief Provides the BAppFileInfo class. 20*/ 21 22 23/*! 24 \class BAppFileInfo 25 \ingroup storage 26 \ingroup libbe 27 \brief Provides access to the metadata associated with executables, 28 libraries and add-ons. 29 30 The BAppFileInfo class allows for information about an executable or 31 add-on to be accessed or set. Information about an executable that can be 32 accessed include the signature, catalog entry, supported MIME types, 33 application flags, icon(s), and version info. 34 35 You should initialize the BAppFileInfo with a BFile object that represents 36 the executable or add-on that you want to access. If you only want to read 37 metadata from the file you do not have to open it for reading. However, if 38 you also want to write metadata then you should open the BFile for writing. 39 40 To associate a BFile with a BAppFileInfo object you can either pass the 41 BFile object into the constructor or you can use the empty constructor and 42 then use the SetTo() method to set the BFile to the BAppFileInfo object. 43 44 When accessing information from a BFileInfo object it will first look in the 45 attributes of the BFile. If the information is not found then the BFileInfo 46 object will next look at the resource of the BFile. You can tell the 47 BFileInfo object to look only in the attributes or resources with the 48 SetInfoLocation() method. 49*/ 50 51 52/*! 53 \fn BAppFileInfo::BAppFileInfo() 54 \brief Creates an uninitialized BAppFileInfo object. 55*/ 56 57 58/*! 59 \fn BAppFileInfo::BAppFileInfo(BFile* file) 60 \brief Creates an BAppFileInfo object and initializes it to the supplied 61 file. 62 63 The caller retains ownership of the supplied BFile object. It must not 64 be deleted during the life time of the BAppFileInfo. It is not deleted 65 when the BAppFileInfo is destroyed. 66 67 \param file The BFile object that the BAppFileInfo object shall be 68 initialized to. 69*/ 70 71 72/*! 73 \fn BAppFileInfo::~BAppFileInfo() 74 \brief Frees all resources associated with this object. 75 76 The supplied BFile object is not deleted if one is specified. 77*/ 78 79 80/*! 81 \fn status_t BAppFileInfo::SetTo(BFile *file) 82 \brief Initializes the BAppFileInfo to the supplied file. 83 84 The caller retains ownership of the supplied BFile object. It must not 85 be deleted during the life time of the BAppFileInfo. The BFile object 86 is not deleted when the BAppFileInfo is destroyed. 87 88 \param file The BFile object that the BAppFileInfo object shall be 89 initialized to. 90 91 \returns an status code. 92 \retval B_OK Everything went fine. 93 \retval B_BAD_VALUE \c NULL \a file or \a file is not properly initialized. 94*/ 95 96 97/*! 98 \name MIME Type 99*/ 100 101 102//! @{ 103 104 105/*! 106 \fn status_t BAppFileInfo::GetType(char *type) const 107 \brief Gets the MIME type of the associated file. 108 109 \param type A pointer to a pre-allocated character buffer of size 110 \c B_MIME_TYPE_LENGTH or larger into which the MIME type of the 111 file will be written. 112 113 \returns A status code. 114 \retval B_OK Everything went fine. 115 \retval B_NO_INIT The object is not properly initialized. 116 \retval B_BAD_VALUE \c NULL \a type or the type string stored in the 117 attribute/resources is longer than \c B_MIME_TYPE_LENGTH. 118 \retval B_BAD_TYPE The attribute/resources the type string is stored in 119 has the wrong type. 120 \retval B_ENTRY_NOT_FOUND No type is set on the file. 121*/ 122 123 124/*! 125 \fn status_t BAppFileInfo::SetType(const char* type) 126 \brief Sets the MIME type of the associated file. 127 128 If \a type is \c NULL if the file's MIME type is unset. 129 130 \param type The MIME type to be assigned to the file. It must not be 131 longer than \c B_MIME_TYPE_LENGTH (including the terminating null). 132 The MIME type may be \c NULL. 133 134 \returns a status code. 135 \retval B_OK Everything went fine. 136 \retval B_NO_INIT The object is not properly initialized. 137 \retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH. 138*/ 139 140 141//! @} 142 143 144/*! 145 \name Signature 146*/ 147 148 149//! @{ 150 151 152/*! 153 \fn status_t BAppFileInfo::GetSignature(char* signature) const 154 \brief Gets the application signature of the associated file. 155 156 \param signature A pointer to a pre-allocated character buffer of size 157 \c B_MIME_TYPE_LENGTH or larger into which the application 158 signature of the file will be written. 159 160 \returns a status code. 161 \retval B_OK Everything went fine. 162 \retval B_NO_INIT The object is not properly initialized. 163 \retval B_BAD_VALUE \c NULL \a signature or the signature stored in the 164 attribute/resources is longer than \c B_MIME_TYPE_LENGTH. 165 \retval B_BAD_TYPE The attribute/resources the signature is stored in have 166 the wrong type. 167 \retval B_ENTRY_NOT_FOUND No signature is set on the file. 168*/ 169 170 171/*! 172 \fn status_t BAppFileInfo::SetSignature(const char* signature) 173 \brief Sets the application signature of the associated file. 174 175 If \a signature is \c NULL the file's application signature is unset. 176 177 \param signature The application signature to be assigned to the file. 178 Must not be longer than \c B_MIME_TYPE_LENGTH (including the 179 terminating \c NUL). The \a signature may be \c NULL. 180 181 \returns a status code. 182 \retval B_OK Everything went fine. 183 \retval B_NO_INIT The object is not properly initialized. 184 \retval B_BAD_VALUE \a signature is longer than \c B_MIME_TYPE_LENGTH. 185*/ 186 187 188//! @} 189 190 191/*! 192 \name Catalog Entry 193*/ 194 195 196//! @{ 197 198 199/*! 200 \fn status_t BAppFileInfo::GetCatalogEntry(char *catalogEntry) const 201 \brief Gets the catalog entry of the associated file used for localization. 202 203 \param catalogEntry A pointer to a pre-allocated character buffer of size 204 \c B_MIME_TYPE_LENGTH * 3 or larger into which the catalog entry 205 of the file will be written. 206 207 \returns a status code. 208 \retval B_OK Everything went fine. 209 \retval B_NO_INIT The object is not properly initialized. 210 \retval B_BAD_VALUE \c NULL \a catalogEntry or the entry stored in the 211 attribute/resources is longer than \c B_MIME_TYPE_LENGTH * 3. 212 \retval B_BAD_TYPE The attribute/resources the entry is stored in have 213 the wrong type. 214 \retval B_ENTRY_NOT_FOUND No catalog entry is set on the file. 215*/ 216 217 218/*! 219 \fn status_t BAppFileInfo::SetCatalogEntry(const char* catalogEntry) 220 \brief Sets the catalog entry of the associated file used for localization. 221 222 If \a catalogEntry is \c NULL the file's catalog entry is unset. 223 224 \param catalogEntry The catalog entry to be assigned to the file. 225 Of the form "x-vnd.Haiku-app:context:name". Must not be longer than 226 \c B_MIME_TYPE_LENGTH * 3 (including the terminating \c NUL). 227 The \a catalogEntry may be \c NULL. 228 229 \returns a status code. 230 \retval B_OK Everything went fine. 231 \retval B_NO_INIT The object is not properly initialized. 232 \retval B_BAD_VALUE \a catalogEntry is longer than 233 \c B_MIME_TYPE_LENGTH * 3. 234*/ 235 236 237//! @} 238 239 240/*! 241 \name Application Flags 242*/ 243 244 245//! @{ 246 247 248/*! 249 \fn status_t BAppFileInfo::GetAppFlags(uint32* flags) const 250 \brief Gets the application \a flags of the associated file. 251 252 \param flags A pointer to a pre-allocated \c uint32 into which the 253 application flags of the file are written. 254 255 \returns A status code. 256 \retval B_OK Everything went fine. 257 \retval B_NO_INIT The object is not properly initialized. 258 \retval B_BAD_VALUE \c NULL \a flags. 259 \retval B_BAD_TYPE The attribute/resources the flags are stored in have 260 the wrong type. 261 \retval B_ENTRY_NOT_FOUND No application flags are set on the file. 262*/ 263 264 265/*! 266 \fn status_t BAppFileInfo::SetAppFlags(uint32 flags) 267 \brief Sets the application \a flags of the associated file. 268 269 \param flags The application \a flags to be assigned to the file. 270 271 \returns A status code. 272 \retval B_OK Everything went fine. 273 \retval B_NO_INIT The object was not properly initialized. 274*/ 275 276 277/*! 278 \fn status_t BAppFileInfo::RemoveAppFlags() 279 \brief Removes the application flags from the associated file. 280 281 \returns A status code. 282 \retval B_OK Everything went fine. 283 \retval B_NO_INIT The object was not properly initialized. 284*/ 285 286 287//! @} 288 289 290/*! 291 \name Supported MIME Types 292*/ 293 294 295//! @{ 296 297 298/*! 299 \fn status_t BAppFileInfo::GetSupportedTypes(BMessage* types) const 300 \brief Gets the MIME types supported by the application. 301 302 The supported MIME types are added to a field "types" of type 303 \c B_STRING_TYPE in \a types. 304 305 \param types A pointer to a pre-allocated BMessage into which the 306 MIME types supported by the application will be written. 307 308 \returns A status code. 309 \retval B_OK Everything went fine. 310 \retval B_NO_INIT The object is not properly initialized. 311 \retval B_BAD_VALUE \c NULL \a types. 312 \retval B_BAD_TYPE The attribute/resources that the supported types 313 are stored in have the wrong type. 314 \retval B_ENTRY_NOT_FOUND No supported types are set on the file. 315*/ 316 317 318/*! 319 \fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types, 320 bool updateMimeDB, bool syncAll) 321 \brief Sets the MIME types that are supported by the application and allows 322 you to specify whether or not the supported types in the MIME DB shall 323 be updated as well. 324 325 If \a types is \c NULL then the application's supported types are unset. 326 327 The supported MIME types must be stored in a field "types" of type 328 \c B_STRING_TYPE in \a types. 329 330 If \a updateMimeDB is \c true, the method will inform the registrar about 331 this news. In this case for each supported type the result of 332 BMimeType::GetSupportingApps() will afterward include the signature of this 333 application. That is, the application file needs to have a signature set. 334 335 \a syncAll specifies whether the no longer supported types shall be 336 updated as well, i.e. whether or not this application shall be removed 337 from the list of supporting applications. Only relevant when \a updateMimeDB 338 is \c true. 339 340 \param types The supported types to be assigned to the file. 341 May be \c NULL. 342 \param updateMimeDB \c true to update the supported types in the MIME DB, 343 \c false otherwise. 344 \param syncAll \c true to also synchronize the no-longer supported 345 types, \c false otherwise. 346 347 \returns A status code. 348 \retval B_OK Everything went fine. 349 \retval B_NO_INIT The object is not properly initialized. 350*/ 351 352 353/*! 354 \fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types, 355 bool syncAll) 356 \brief Sets the MIME types that are supported by the application and allows 357 you to specify whether or not the no longer supported types shall be 358 updated as well. 359 360 If \a types is \c NULL then the application's supported types are unset. 361 362 The supported MIME types must be stored in a field "types" of type 363 \c B_STRING_TYPE in \a types. 364 365 The method informs the registrar about this news. 366 For each supported type the result of BMimeType::GetSupportingApps() 367 will afterwards include the signature of this application. That is, 368 the application file needs to have a signature set. 369 370 \a syncAll specifies whether the no longer supported types shall be 371 updated as well, i.e. whether or not this application shall be removed 372 from the list of supporting applications. 373 374 \param types The supported types to be assigned to the file. 375 May be \c NULL. 376 \param syncAll \c true to also synchronize the no-longer supported 377 types, \c false otherwise. 378 379 \returns A status code. 380 \retval B_OK Everything went fine. 381 \retval B_NO_INIT The object is not properly initialized. 382*/ 383 384 385/*! 386 \fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types) 387 \brief Sets the MIME types supported by the application. 388 389 This method is a short-hand for SetSupportedTypes(types, false). 390 \see SetSupportedType(const BMessage*, bool) for detailed information. 391 392 \param types The supported types to be assigned to the file. 393 May be \c NULL. 394 \returns A status code. 395 \retval B_OK Everything went fine. 396 \retval B_NO_INIT The object is not properly initialized. 397*/ 398 399 400/*! 401 \fn bool BAppFileInfo::IsSupportedType(const char* type) const 402 \brief Returns whether the application supports the supplied MIME type. 403 404 If the application supports the wildcard type "application/octet-stream" 405 then this method returns \c true for any MIME type. 406 407 \param type The MIME type in question. 408 409 \returns \c true if \a type is a valid MIME type and it is supported by 410 the application, \c false otherwise. 411*/ 412 413 414/*! 415 \fn bool BAppFileInfo::Supports(BMimeType* type) const 416 \brief Returns whether the application supports the supplied MIME type 417 explicitly. 418 419 Unlike IsSupportedType(), this method returns \c true, only if the type 420 is explicitly supported, regardless of whether it supports 421 "application/octet-stream". 422 423 \param type The MIME type in question. 424 425 \returns \c true if \a type is a valid MIME type and it is explicitly 426 supported by the application, \c false otherwise. 427*/ 428 429 430//! @} 431 432 433/*! 434 \name Application Icon 435*/ 436 437 438//! @{ 439 440 441/*! 442 \fn status_t BAppFileInfo::GetIcon(BBitmap* icon, icon_size which) const 443 \brief Gets the icon of the associated file and puts it into a pre-allocated 444 BBitmap. 445 446 \param icon A pointer to a pre-allocated BBitmap of the correct dimension 447 to store the requested icon (16x16 for the \c B_MINI_ICON and 32x32 448 for the \c B_LARGE_ICON). 449 \param which Specifies the size of the icon to be retrieved: 450 \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon. 451 For HVIF icons this parameter has no effect. 452 453 \returns A status code. 454 \retval B_OK Everything went fine. 455 \retval B_NO_INIT The object is not properly initialized. 456 \retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a which or 457 bitmap dimensions (\a icon) and icon size (\a which) do not match. 458*/ 459 460 461/*! 462 \fn status_t BAppFileInfo::GetIcon(uint8** data, size_t* size) const 463 \brief Gets the icon of the associated file and puts it into a buffer. 464 465 \param data The pointer in which the flat icon data will be returned. 466 \param size The pointer in which the size of the data found will be 467 returned. 468 469 \returns A status code. 470 \retval B_OK Everything went fine. 471 \retval B_NO_INIT The object is not properly initialized. 472 \retval B_BAD_VALUE \c NULL \a data or \c NULL size. 473*/ 474 475 476/*! 477 \fn status_t BAppFileInfo::SetIcon(const BBitmap* icon, icon_size which, 478 bool updateMimeDB) 479 \brief Sets the icon of the associated file from a BBitmap. 480 481 If \a icon is \c NULL then the icon of the file is unset. 482 483 \param icon A pointer to the BBitmap containing the icon to be set. 484 May be \c NULL to specify no icon. 485 \param which Specifies the size of the icon to be set: \c B_MINI_ICON for 486 16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon. 487 For HVIF icons this parameter has no effect. 488 \param updateMimeDB \c true to also set the icon for the application in the 489 MIME DB. \c false otherwise. 490 491 \returns A status code. 492 \retval B_OK Everything went fine. 493 \retval B_NO_INIT The object is not properly initialized. 494 \retval B_BAD_VALUE Unknown icon size \a which or bitmap dimensions 495 (\a icon) and icon size (\a which) do not match. 496*/ 497 498/*! 499 \fn status_t BAppFileInfo::SetIcon(const BBitmap* icon, icon_size which) 500 \brief Sets the icon of the associated file from a BBitmap. 501 502 If \a icon is \c NULL then the icon of the file is unset. 503 504 Also sets the application's icon in the MIME DB, if the file has a valid 505 application signature. 506 507 \param icon A pointer to the BBitmap containing the icon to be set. 508 May be \c NULL to specify no icon. 509 \param which Specifies the size of the icon to be set: \c B_MINI_ICON for 510 16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon. 511 For HVIF icons this parameter has no effect. 512 513 \returns A status code. 514 \retval B_OK Everything went fine. 515 \retval B_NO_INIT The object is not properly initialized. 516 \retval B_BAD_VALUE Unknown icon size \a which or bitmap dimensions 517 (\a icon) and icon size (\a which) do not match. 518*/ 519 520 521/*! 522 \fn status_t BAppFileInfo::SetIcon(const uint8* data, size_t size, 523 bool updateMimeDB) 524 \brief Sets the icon of the associated file from a buffer. 525 526 If \a data is \c NULL then the icon of the file is unset. 527 528 \param data A pointer to the data buffer containing the vector icon 529 to be set. May be \c NULL. 530 \param size Specifies the size of buffer pointed to by \a data. 531 \param updateMimeDB \c true to also set the icon for the application in the 532 MIME DB. \c false otherwise. 533 534 \returns A status code. 535 \retval B_OK Everything went fine. 536 \retval B_NO_INIT The object is not properly initialized. 537 \retval B_BAD_VALUE \c NULL data. 538*/ 539 540 541/*! 542 \fn status_t BAppFileInfo::SetIcon(const uint8* data, size_t size) 543 \brief Sets the icon of the associated file from a buffer. 544 545 If \a data is \c NULL then the icon of the file is unset. 546 547 Also sets the application's icon in the MIME DB, if the file has a valid 548 application signature. 549 550 \param data A pointer to the data buffer containing the vector icon 551 to be set. May be \c NULL. 552 \param size Specifies the size of buffer pointed to by \a data. 553 554 \returns A status code. 555 \retval B_OK Everything went fine. 556 \retval B_NO_INIT The object is not properly initialized. 557 \retval B_BAD_VALUE \c NULL data. 558*/ 559 560 561/*! 562 \fn status_t BAppFileInfo::GetIconForType(const char* type, BBitmap* icon, 563 icon_size size) const 564 \brief Gets the icon the application provides for a given MIME type and 565 puts it into a BBitmap. 566 567 \note If \a type is \c NULL, the application's icon is retrieved. 568 569 \param type The MIME type in question. May be \c NULL. 570 \param icon A pointer to a pre-allocated BBitmap of the correct dimension 571 to store the requested icon (16x16 for the mini and 32x32 for the 572 large icon). 573 \param size Specifies the size of the icon to be retrieved: 574 \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon. 575 576 \returns A status code. 577 \retval B_OK Everything went fine. 578 \retval B_NO_INIT The object is not properly initialized. 579 \retval B_BAD_VALUE \c NULL \a icon, unsupported icon size 580 \a which or bitmap dimensions (\a icon) and icon size (\a which) do 581 not match. 582*/ 583 584 585/*! 586 \fn status_t BAppFileInfo::GetIconForType(const char* type, uint8** data, 587 size_t* size) const 588 \brief Gets the icon the application provides for a given MIME type and 589 puts it into a buffer. 590 591 \note If \a type is set to \c NULL the the application's icon is retrieved. 592 593 \param type The MIME type in question. May be \c NULL. 594 \param data A pointer in which the icon data will be returned. When you 595 are done with the data, you should use free() to deallocate it. 596 \param size A pointer in which the size of the retrieved data is returned. 597 598 \returns A status code. 599 \retval B_OK Everything went fine. 600 \retval B_NO_INIT The object is not properly initialized. 601 \retval B_BAD_VALUE \c NULL \a data and/or \a size. Or the supplied 602 \a type is not a valid MIME type. 603*/ 604 605 606/*! 607 \fn status_t BAppFileInfo::SetIconForType(const char* type, 608 const BBitmap* icon, icon_size which, bool updateMimeDB) 609 \brief Sets the icon the application provides for a given MIME type from a 610 BBitmap. 611 612 \note If \a type is \c NULL then the icon is set. 613 \note If \a icon is \c NULL then the icon is unset. 614 615 If \a updateMimeDB is \c true and if the file has a signature, then the icon 616 is also set on the MIME type. If the type for the signature has not been 617 installed yet, it is installed before. 618 619 \param type The MIME type in question. May be \c NULL. 620 \param icon A pointer to the BBitmap containing the icon to be set. 621 May be \c NULL. 622 \param which Specifies the size of the icon to be set: \c B_MINI_ICON 623 for the mini and \c B_LARGE_ICON for the large icon. 624 \param updateMimeDB \c true to also set the icon for the type in the MIME 625 DB. \c false otherwise. 626 627 \returns A status code. 628 \retval B_OK Everything went fine. 629 \retval B_NO_INIT The object is not properly initialized. 630 \retval B_BAD_VALUE Either the icon size \a which is unknown, 631 the bitmap dimensions (\a icon) and icon size (\a which) do not 632 match, or the provided \a type is not a valid MIME type. 633*/ 634 635 636/*! 637 \fn status_t BAppFileInfo::SetIconForType(const char* type, 638 const BBitmap* icon, icon_size which) 639 \brief Sets the icon the application provides for a given MIME type from a 640 BBitmap. 641 642 \note If \a type is \c NULL then the icon is set. 643 \note If \a icon is \c NULL then the icon is unset. 644 645 If the file has a signature, then the icon is also set on the MIME type. 646 If the type for the signature has not been installed yet, it is installed 647 before. 648 649 \param type The MIME type in question. May be \c NULL. 650 \param icon A pointer to the BBitmap containing the icon to be set. 651 May be \c NULL. 652 \param which Specifies the size of the icon to be set: \c B_MINI_ICON 653 for the mini and \c B_LARGE_ICON for the large icon. 654 655 \returns A status code. 656 \retval B_OK Everything went fine. 657 \retval B_NO_INIT The object is not properly initialized. 658 \retval B_BAD_VALUE Either the icon size \a which is unknown, 659 the bitmap dimensions (\a icon) and icon size (\a which) do not 660 match, or the provided \a type is not a valid MIME type. 661*/ 662 663 664/*! 665 \fn status_t BAppFileInfo::SetIconForType(const char* type, 666 const uint8* data, size_t size, bool updateMimeDB) 667 \brief Sets the icon the application provides for a given MIME type from a 668 buffer. 669 670 \note If \a type is \c NULL then the icon is set. 671 \note If \a data is \c NULL then the icon is unset. 672 673 If \a updateMimeDB is \c true and if the file has a signature, then the icon 674 is also set on the MIME type. If the type for the signature has not been 675 installed yet, it is installed before. 676 677 \param type The MIME type in question. May be \c NULL. 678 \param data A pointer to the data containing the icon to be set. 679 May be \c NULL. 680 \param size Specifies the size of buffer provided in \a data. 681 \param updateMimeDB \c true to also set the icon for the type in the MIME 682 DB. \c false otherwise. 683 684 \returns A status code. 685 \retval B_OK Everything went fine. 686 \retval B_NO_INIT The object is not properly initialized. 687 \retval B_BAD_VALUE The provided \a type is not a valid MIME type. 688*/ 689 690 691/*! 692 \fn status_t BAppFileInfo::SetIconForType(const char* type, 693 const uint8* data, size_t size) 694 \brief Sets the icon the application provides for a given MIME type from a 695 buffer. 696 697 \note If \a type is \c NULL then the icon is set. 698 \note If \a data is \c NULL then the icon is unset. 699 700 If the file has a signature, then the icon is also set on the MIME type. 701 If the type for the signature has not been installed yet, it is 702 installed before. 703 704 \param type The MIME type in question. May be \c NULL. 705 \param data A pointer to the data containing the icon to be set. 706 May be \c NULL. 707 \param size Specifies the size of buffer provided in \a data. 708 709 \returns A status code. 710 \retval B_OK Everything went fine. 711 \retval B_NO_INIT The object is not properly initialized. 712 \retval B_BAD_VALUE The provided \a type is not a valid MIME type. 713*/ 714 715 716//! @} 717 718 719/*! 720 \name Version Info 721*/ 722 723 724//! @{ 725 726 727/*! 728 \fn status_t BAppFileInfo::GetVersionInfo(version_info* info, 729 version_kind kind) const 730 \brief Gets the version info of the associated file. 731 732 \param info A pointer to a pre-allocated version_info structure into 733 which the version info should be written. 734 \param kind Specifies the kind of the version info to be retrieved: 735 - \c B_APP_VERSION_KIND for the application's version info and 736 - \c B_SYSTEM_VERSION_KIND for the suite's info the application 737 belongs to. 738 739 \returns A status code. 740 \retval B_OK Everything went fine. 741 \retval B_NO_INIT The object is not properly initialized. 742 \retval B_BAD_VALUE \c NULL \a info. 743*/ 744 745 746/*! 747 \fn status_t BAppFileInfo::SetVersionInfo(const version_info* info, 748 version_kind kind) 749 \brief Sets the version info of the associated file. 750 751 \note If \a info is set to \c NULL then the file's version info is unset. 752 753 \param info The version info to be set. May be \c NULL. 754 \param kind Specifies kind of version info to be set: 755 - \c B_APP_VERSION_KIND for the application's version info and 756 - \c B_SYSTEM_VERSION_KIND for the suite's info the application 757 belongs to. 758 759 \returns A status code. 760 \retval B_OK Everything went fine. 761 \retval B_NO_INIT The object is not properly initialized. 762*/ 763 764 765//! @} 766 767 768/*! 769 \name Attributes/Resources 770*/ 771 772 773//! @{ 774 775 776/*! 777 \fn void BAppFileInfo::SetInfoLocation(info_location location) 778 \brief Specifies the location where the metadata shall be stored. 779 780 The options for \a location are: 781 - \c B_USE_ATTRIBUTES: Store the data in the attributes. 782 - \c B_USE_RESOURCES: Store the data in the resources. 783 - \c B_USE_BOTH_LOCATIONS: Store the data in attributes and resources. 784 785 \param location The location where the metadata shall be stored. 786*/ 787 788 789/*! 790 \fn bool BAppFileInfo::IsUsingAttributes() const 791 \brief Returns whether the object (also) stores the metadata in the 792 attributes of the associated file. 793 794 \returns \c true if the metadata are (also) stored in the file's 795 attributes, \c false otherwise. 796*/ 797 798 799/*! 800 \fn bool BAppFileInfo::IsUsingResources() const 801 \brief Returns whether the object (also) stores the metadata in the 802 resources of the associated file. 803 804 \returns \c true if the metadata are (also) stored in the file's 805 resources, \c false otherwise. 806*/ 807 808 809//! @} 810 811 812/*! 813 \fn BAppFileInfo & BAppFileInfo::operator=(const BAppFileInfo &) 814 \brief Privatized assignment operator to prevent usage. 815*/ 816 817 818/*! 819 \fn BAppFileInfo::BAppFileInfo(const BAppFileInfo &) 820 \brief Privatized copy constructor to prevent usage. 821*/ 822 823 824/*! 825 \fn status_t BAppFileInfo::GetMetaMime(BMimeType* meta) const 826 \brief Initializes a BMimeType to the signature of the associated file. 827 828 \warning The parameter \a meta is not checked. 829 830 \param meta A pointer to a pre-allocated BMimeType that shall be 831 initialized to the signature of the associated file. 832 833 \returns A status code. 834 \retval B_OK Everything went fine. 835 \retval B_BAD_VALUE \c NULL \a meta 836 \retval B_ENTRY_NOT_FOUND The file has not signature or the signature is 837 (not installed in the MIME database.) no valid MIME string. 838*/ 839 840 841/*! 842 \fn status_t BAppFileInfo::_ReadData(const char* name, int32 id, 843 type_code type, void* buffer, size_t bufferSize, 844 size_t &bytesRead, void** allocatedBuffer) const 845 \brief Reads data from an attribute or resource. 846 847 \note The data is read from the location specified by \a fWhere. 848 849 \warning The object must be properly initialized. The parameters are 850 \b NOT checked. 851 852 \param name The name of the attribute/resource to be read. 853 \param id The resource ID of the resource to be read. It is ignored 854 when < 0. 855 \param type The type of the attribute/resource to be read. 856 \param buffer A pre-allocated buffer for the data to be read. 857 \param bufferSize The size of the supplied buffer. 858 \param bytesRead A reference parameter, set to the number of bytes 859 actually read. 860 \param allocatedBuffer If not \c NULL, the method allocates a buffer 861 large enough too store the whole data and writes a pointer to it 862 into this variable. If \c NULL, the supplied buffer is used. 863 864 \returns A status code. 865 \retval B_OK Everything went fine. 866 \retval B_ENTRY_NOT_FOUND The entry was not found. 867 \retval B_NO_MEMORY Ran out of memory allocating the buffer. 868 \retval B_BAD_VALUE \a type did not match. 869*/ 870 871 872/*! 873 \fn status_t BAppFileInfo::_WriteData(const char* name, int32 id, 874 type_code type, const void* buffer, size_t bufferSize, bool findID) 875 \brief Writes data to an attribute or resource. 876 877 \note The data is written to the location(s) specified by \a fWhere. 878 879 \warning The object must be properly initialized. The parameters are 880 \b NOT checked. 881 882 \param name The name of the attribute/resource to be written. 883 \param id The resource ID of the resource to be written. 884 \param type The type of the attribute/resource to be written. 885 \param buffer A buffer containing the data to be written. 886 \param bufferSize The size of the supplied buffer. 887 \param findID If set to \c true use the ID that is already assigned to the 888 \a name / \a type pair or take the first unused ID >= \a id. 889 If \c false, \a id is used. 890 891 \returns A status code. 892 \retval B_OK Everything went fine. 893 \retval B_ERROR An error occurred while trying to write the data. 894*/ 895 896 897/*! 898 \fn status_t BAppFileInfo::_RemoveData(const char* name, type_code type) 899 \brief Removes an attribute or resource. 900 901 \note The removal location is specified by \a fWhere. 902 903 \warning The object must be properly initialized. The parameters are 904 \b NOT checked. 905 906 \param name The name of the attribute/resource to be remove. 907 \param type The type of the attribute/resource to be removed. 908 909 \returns A status code. 910 \retval B_OK Everything went fine. 911 \retval B_NO_INIT Not using attributes and not using resources. 912 \retval B_ENTRY_NOT_FOUND The attribute or resource was not found. 913*/ 914