docs/user/storage/AppFileInfo.dox

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