1/* 2 * Copyright 2011-2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Ingo Weinhold, bonefish@users.sf.net 7 * Axel D��rfler, axeld@pinc-software.de 8 * John Scipione, jscipione@gmail.com 9 * 10 * Corresponds to: 11 * headers/os/storage/MimeType.h hrev47402 12 * src/kits/storage/MimeType.cpp hrev47402 13 */ 14 15 16/*! 17 \file MimeType.h 18 \ingroup storage 19 \ingroup libbe 20 \brief Provides the BMimeType class. 21*/ 22 23 24/*! 25 \class BMimeType 26 \ingroup storage 27 \ingroup libbe 28 \brief A class that represents a MIME (Multi-purpose Internet Mail 29 Extensions) type string. 30 31 MIME types use, has grown beyond describing the content of email 32 to describe the content types of applications and file formats. 33 34 MIME types consist of a supertype and a subtype. 35 36 \since BeOS R3 37*/ 38 39 40/*! 41 \fn BMimeType::BMimeType() 42 \brief Creates an uninitialized BMimeType object. 43 44 \since BeOS R3 45*/ 46 47 48/*! 49 \fn BMimeType::BMimeType(const char* mimeType) 50 \brief Creates a BMimeType object and initializes it to the supplied 51 MIME type. 52 53 The supplied string must specify a valid MIME type or supertype. 54 55 \param mimeType The MIME string. 56 57 \sa SetTo() for further information. 58 59 \since BeOS R3 60*/ 61 62 63/*! 64 \fn BMimeType::~BMimeType() 65 \brief Frees all resources associated with this object. 66 67 \since BeOS R3 68*/ 69 70 71/*! 72 \fn status_t BMimeType::SetTo(const char* mimeType) 73 \brief Initializes this object to the supplied MIME type. 74 75 The supplied string must specify a valid MIME type or supertype. 76 Valid MIME types are given by the following grammar: 77 78 MIMEType ::= Supertype "/" [ Subtype ] 79 Supertype ::= "application" | "audio" | "image" | "message" 80 | "multipart" | "text" | "video" 81 Subtype ::= MIMEChar MIMEChar* 82 MIMEChar ::= any character except white spaces, CTLs and '/', '<', '>', 83 '@',, ',', ';', ':', '"', '(', ')', '[', ']', '?', '=', '\' 84 (Note: RFC1341 also forbits '.', but it is allowed here.) 85 86 Currently the supertype is not restricted to one of the seven types given, 87 but can be an arbitrary string (obeying the same rule as the subtype). 88 Nevertheless it is a very bad idea to use another supertype. 89 The supplied MIME string is copied; the caller retains the ownership. 90 91 \param mimeType The MIME string. 92 93 \returns A status code. 94 \retval B_OK Everything went fine. 95 \retval B_BAD_VALUE Invalid \a mimeType string. 96 \retval B_NO_INIT BMimeType was uninitialized. 97 \retval B_NO_MEMORY Insufficient memory to copy the MIME string. 98 99 \since BeOS R3 100*/ 101 102 103/*! 104 \fn void BMimeType::Unset() 105 \brief Returns the object to an uninitialized state. 106 107 \since BeOS R3 108*/ 109 110 111/*! 112 \fn status_t BMimeType::InitCheck() const 113 \brief Returns the result of the most recent constructor or SetTo() call. 114 115 \returns \c B_OK If the object is properly initialized, a specific 116 error code otherwise. 117 118 \since BeOS R3 119*/ 120 121 122/*! 123 \fn const char* BMimeType::Type() const 124 \brief Returns the MIME string represented by this object. 125 126 \return The MIME string, if the object is properly initialized, \c NULL 127 otherwise. 128 129 \since BeOS R3 130*/ 131 132 133/*! 134 \fn bool BMimeType::IsValid() const 135 \brief Returns whether the object represents a valid MIME type. 136 137 \return \c true, if the object is properly initialized, \c false 138 otherwise. 139 140 \sa SetTo() for further information. 141 142 \since BeOS R3 143*/ 144 145 146/*! 147 \fn bool BMimeType::IsSupertypeOnly() const 148 \brief Returns whether this objects represents a supertype. 149 150 \return \c true, if the object is properly initialized and represents a 151 supertype, \c false otherwise. 152 153 \since BeOS R3 154*/ 155 156 157/*! 158 \fn bool BMimeType::IsInstalled() const 159 \brief Returns whether or not this type is currently installed in the 160 MIME database. 161 162 To add the MIME type to the database, call \c Install(). 163 To remove the MIME type from the database, call \c Delete(). 164 165 \return A \c bool indicating whether or not this type is currently 166 installed in the MIME database. 167 \retval true The MIME type is currently installed in the database. 168 \retval false The MIME type is not currently installed in the database. 169 170 \since BeOS R3 171*/ 172 173 174/*! 175 \fn status_t BMimeType::GetSupertype(BMimeType* supertype) const 176 \brief Gets the \a supertype of the MIME type represented by this object. 177 178 The supplied object is initialized to this object's \a supertype. If this 179 BMimeType is not properly initialized, the supplied object will be Unset(). 180 181 \param supertype A pointer to the BMimeType object that shall be 182 initialized to this object's \a supertype. 183 184 \returns A status code. 185 \retval B_OK Everything went fine. 186 \retval B_BAD_VALUE \c NULL \a superType, this object is not initialized, 187 or this object is a supertype only. 188 \retval B_NO_INIT BMimeType was uninitialized. 189 190 \since BeOS R3 191*/ 192 193 194/*! 195 \fn bool BMimeType::operator==(const BMimeType &type) const 196 \brief Returns whether this and the supplied MIME type are equal. 197 198 Two BMimeType objects are said to be equal if they represent the same 199 MIME string, ignoring case, or if both are not initialized. 200 201 \warning In BeOS R5 two uninitialized BMimeType objects were not 202 considered to be equal, in Haiku they are. 203 204 \param type The BMimeType to be compared with. 205 206 \return \c true, if the objects are equal, \c false otherwise. 207 208 \since BeOS R3 209*/ 210 211 212/*! 213 \fn bool BMimeType::operator==(const char* type) const 214 \brief Returns whether this and the supplied MIME type are equal. 215 216 A BMimeType objects equals a MIME string, if its MIME string equals the 217 latter one, ignoring case, or if it is uninitialized and the MIME string 218 is \c NULL. 219 220 \warning In BeOS R5 an uninitialized BMimeType object was not 221 considered to be equal to \c NULL, in Haiku it is. 222 223 \param type The MIME string to be compared with. 224 225 \return \c true, if the MIME types are equal, \c false otherwise. 226 227 \since BeOS R4 228*/ 229 230 231/*! 232 \fn bool BMimeType::Contains(const BMimeType* type) const 233 \brief Returns whether this MIME type is a supertype of or equals the 234 supplied one. 235 236 \param type The MIME type. 237 238 \returns \c true, if this MIME type is a supertype of or equals the 239 supplied one, \c false otherwise. 240 241 \since BeOS R3 242*/ 243 244 245/*! 246 \fn status_t BMimeType::Install() 247 \brief Adds the MIME type to the MIME database. 248 249 To check if the MIME type is already installed, call \c IsInstalled(). 250 To remove the MIME type from the database, call \c Delete(). 251 252 \note The R5 implementation returns random values if the type is already 253 installed, so be sure to check \c IsInstalled() first. 254 255 \returns \c B_OK on success or another error code on failure. 256 257 \see Delete() 258 259 \since BeOS R3 260*/ 261 262 263/*! 264 \fn status_t BMimeType::Delete() 265 \brief Removes the MIME type from the MIME database. 266 267 To check if the MIME type is already installed, call \c IsInstalled(). 268 To add the MIME type to the database, call \c Install(). 269 270 \note Calling \c BMimeType::Delete() does not uninitialize or otherwise 271 deallocate the \c BMimeType object; it simply removes the type from 272 the database. 273 274 \returns \c B_OK on success or another error code on failure. 275 276 \since BeOS R3 277*/ 278 279 280/*! 281 \fn status_t BMimeType::GetIcon(BBitmap* icon, icon_size size) const 282 \brief Fetches the large or mini icon associated with the MIME type. 283 284 The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap 285 must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini 286 icon. Additionally, the bitmap must be in the \c B_CMAP8 color space 287 (8-bit color). 288 289 \param icon Pointer to a pre-allocated \c BBitmap of proper size and 290 colorspace into which the icon is copied. 291 \param size Value that specifies which icon to return. 292 Currently \c B_LARGE_ICON and \c B_MINI_ICON are supported. 293 294 \returns A status code. 295 \retval B_OK Everything went fine. 296 \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the 297 given type. 298 \retval B_NO_INIT BMimeType was uninitialized. 299 300 \since BeOS R3 301*/ 302 303 304/*! 305 \fn status_t BMimeType::GetIcon(uint8** data, size_t* size) const 306 \brief Fetches the vector icon associated with the MIME type 307 The icon data is returned in \c data. 308 309 \param data Pointer in which the allocated icon data is returned. You 310 need to delete the buffer when you are done with it. 311 \param size Pointer in which the size of the allocated icon data is 312 returned. 313 314 \returns A status code. 315 \retval B_OK Everything went fine. 316 \retval B_ENTRY_NOT_FOUND No icon of the given size found for the given 317 type. 318 \retval B_NO_INIT BMimeType was uninitialized. 319 320 \since BeOS R3 321*/ 322 323 324/*! 325 \fn status_t BMimeType::GetPreferredApp(char* signature, 326 app_verb verb) const 327 \brief Fetches the signature of the preferred application from 328 the MIME database. 329 330 The preferred app is the application that's used to access a file when, 331 for example, the user double-clicks the file in a Tracker window. Unless 332 the file identifies in its attributes a "custom" preferred app, Tracker 333 will ask the file type database for the preferred app 334 that's associated with the file's type. 335 336 The string pointed to by \c signature must be long enough to 337 hold the preferred applications signature; a length of 338 \c B_MIME_TYPE_LENGTH is recommended. 339 340 \param signature Pointer to a pre-allocated string into which the 341 signature of the preferred app is copied. If the function fails, 342 the contents of the string are undefined. 343 \param verb \c app_verb value that specifies the type of access for 344 which you are requesting the preferred app. Currently, the only 345 supported app verb is \c B_OPEN. 346 347 \returns A status code. 348 \retval B_OK Success 349 \retval B_ENTRY_NOT_FOUND No preferred app exists for the given type 350 and app_verb. 351 \retval B_NO_INIT BMimeType was uninitialized. 352 353 \see SetPreferredApp() 354 355 \since BeOS R3 356*/ 357 358 359/*! 360 \fn status_t BMimeType::GetAttrInfo(BMessage* info) const 361 \brief Fetches from the MIME database a BMessage describing the attributes 362 typically associated with files of the given MIME type. 363 364 The attribute information is returned in a pre-allocated BMessage pointed 365 to by the \c info parameter (note that the any prior contents of the 366 message will be destroyed). If the method succeeds, the format of the 367 BMessage pointed to by \c info will be the following: 368 369 <table> 370 <tr> 371 <td><b>field name</b></td> 372 <td><b>type</b></td> 373 <td><b>element[0..n]</b></td> 374 </tr> 375 <tr> 376 <td> "attr:name"</td> 377 <td> \c B_STRING_TYPE </td> 378 <td> The name of each attribute </td> 379 </tr> 380 <tr> 381 <td> "attr:public_name"</td> 382 <td> \c B_STRING_TYPE </td> 383 <td> The human-readable name of each attribute </td> 384 </tr> 385 <tr> 386 <td> "attr:type"</td> 387 <td> \c B_INT32_TYPE </td> 388 <td> The type code for each attribute </td> 389 </tr> 390 <tr> 391 <td> "attr:viewable"</td> 392 <td> \c B_BOOL_TYPE </td> 393 <td> For each attribute: \c true if the attribute is public, 394 \c false if it's private </td> 395 </tr> 396 <tr> 397 <td> "attr:editable"</td> 398 <td> \c B_BOOL_TYPE </td> 399 <td> For each attribute: \c true if the attribute should be user 400 editable, \c false if not </td> 401 </tr> 402 </table> 403 404 The \c BMessage::what value is set to decimal \c 233, but is otherwise 405 meaningless. 406 407 \param info Pointer to a pre-allocated BMessage into which information about 408 the MIME type's associated file attributes is stored. 409 410 \returns \c B_OK on success or another error code on failure. 411 412 \see SetAttrInfo() 413 414 \since BeOS R3 415*/ 416 417 418/*! 419 \fn status_t BMimeType::GetFileExtensions(BMessage* extensions) const 420 \brief Fetches the MIME type's associated filename extensions from the 421 MIME database. 422 423 The MIME database associates a list of filename extensions (a character 424 string following the rightmost dot, \c ".", character in the filename) 425 with each type. These extensions can then be used to help determine the 426 type of any untyped files that may be encountered. 427 428 The list of extensions is returned in a pre-allocated BMessage pointed 429 to by the \c extensions parameter (note that the any prior contents of 430 the message will be destroyed). If the method succeeds, the format of 431 the BMessage pointed to by \c extensions will be the following: 432 433 - The message's \c "extensions" field will contain an indexed array 434 of strings, one for each extension. The extensions are given 435 without the preceding \c "." character by convention. 436 - The message's \c "type" field will be a string containing the 437 MIME type whose associated file extensions you are fetching. 438 - The \c what member of the BMessage will be set to \c 234, but 439 is otherwise irrelevant. 440 441 Note that any other fields present in the BMessage passed to the most 442 recent \c SetFileExtensions() call will also be returned. 443 444 \param extensions Pointer to a pre-allocated BMessage into which the 445 MIME type's associated file extensions will be stored. 446 447 \returns \c B_OK on success or another error code on failure. 448 449 \see SetFileExtensions() 450 451 \since BeOS R3 452*/ 453 454 455/*! 456 \fn status_t BMimeType::GetShortDescription(char* description) const 457 \brief Fetches the MIME type's short description from the MIME database. 458 459 The string pointed to by \c description must be long enough to 460 hold the short description; a length of \c B_MIME_TYPE_LENGTH is 461 recommended. 462 463 \param description Pointer to a pre-allocated string into which the long 464 description is copied. If the function fails, the contents of the 465 string are undefined. 466 467 \returns A status code. 468 \retval B_OK Success 469 \retval B_ENTRY_NOT_FOUND No short description exists for the given type. 470 \retval B_NO_INIT BMimeType was uninitialized. 471 472 \see SetShortDescription() 473 474 \since BeOS R3 475*/ 476 477 478/*! 479 \fn status_t BMimeType::GetLongDescription(char* description) const 480 \brief Fetches the MIME type's long description from the MIME database. 481 482 The string pointed to by \c description must be long enough to 483 hold the long description; a length of \c B_MIME_TYPE_LENGTH is 484 recommended. 485 486 \param description Pointer to a pre-allocated string into which the 487 long description is copied. If the function fails, the contents 488 of the string are undefined. 489 490 \returns A status code. 491 \retval B_OK Success 492 \retval B_ENTRY_NOT_FOUND No long description exists for the given type. 493 \retval B_NO_INIT BMimeType was uninitialized. 494 495 \see SetLongDescription() 496 497 \since BeOS R3 498*/ 499 500 501/*! 502 \fn status_t BMimeType::GetSupportingApps(BMessage* signatures) const 503 \brief Fetches a \c BMessage containing a list of MIME signatures of 504 applications that are able to handle files of this MIME type. 505 506 If successful, the BMessage containing the MIME signatures will be of 507 the following format: 508 509 <table> 510 <tr> 511 <td><b>field name</b></td> 512 <td><b>type</b></td> 513 <td><b>contains</b></td> 514 </tr> 515 <tr> 516 <td> "applications"</td> 517 <td> \c B_STRING_TYPE[] </td> 518 <td> 519 An array of MIME signatures. The first <i> n </i> signatures 520 (where <i> n </i> is the value in the \c "be:sub" field of the 521 message) are able to handle the full type (supertype 522 <i> and </i> subtype). The remaining signatures are of 523 applications that handle the supertype only. 524 </td> 525 </tr> 526 <tr> 527 <td> "be:sub"</td> 528 <td> \c B_INT32_TYPE </td> 529 <td> 530 The number of applications in the \c "applications" array that 531 can handle the object's full MIME type. These applications are 532 listed first in the array. This field is omitted if the object 533 represents a supertype only. 534 </td> 535 </tr> 536 <tr> 537 <td> "be:super"</td> 538 <td> \c B_INT32_TYPE </td> 539 <td> 540 The number of applications in the "applications" array that can 541 handle the object's supertype (not counting those that can 542 handle the full type). 543 These applications are listed after the full-MIME-type 544 supporters. By definition, the \c GetWildcardApps() function 545 never returns supertype-only apps. 546 </td> 547 </tr> 548 </table> 549 550 The \c BMessage::what value is meaningless and should be ignored. 551 552 \param signatures Pointer to a pre-allocated BMessage into which the 553 signatures of the supporting applications will be copied. 554 555 \returns \c B_OK on success or an error code on failure. 556 557 \see SetSupportingApps() 558 559 \since BeOS R3 560*/ 561 562 563/*! 564 \fn status_t BMimeType::SetIcon(const BBitmap* icon, icon_size which) 565 \brief Sets the large or mini icon for the MIME type. 566 567 The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap 568 must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini 569 icon. Additionally, the bitmap must be in the \c B_CMAP8 color space (8-bit 570 color). 571 572 If you want to erase the current icon, pass \c NULL as the \c icon argument. 573 574 \param icon Pointer to a pre-allocated \c BBitmap of proper size and 575 colorspace containing the new icon, or \c NULL to clear the current 576 icon. 577 \param which Value that specifies which icon to update. Currently 578 \c B_LARGE_ICON and \c B_MINI_ICON are supported. 579 580 \returns \c B_OK on success or another error code on failure. 581 582 \since BeOS R3 583*/ 584 585 586/*! 587 \fn status_t BMimeType::SetIcon(const uint8* data, size_t size) 588 \brief Sets the vector icon for the MIME type 589 590 The icon is copied from the provided \a data which must contain 591 \a size bytes. 592 593 If you want to erase the current icon, pass \c NULL as the \a data argument. 594 595 \param data Pointer to a buffer containing the new icon, or \c NULL to clear 596 the current icon. 597 \param size Size of the provided buffer. 598 599 \returns \c B_OK on success or another error code on failure. 600 601 \since Haiku R1 602*/ 603 604 605/*! 606 \fn status_t BMimeType::SetPreferredApp(const char* signature, 607 app_verb verb) 608 \brief Sets the preferred application for the MIME type. 609 610 The preferred app is the application that's used to access a file when, 611 for example, the user double-clicks the file in a Tracker window. Unless 612 the file identifies in its attributes a "custom" preferred app, Tracker 613 will ask the file type database for the preferred app that's associated 614 with the file's type. 615 616 The string pointed to by \c signature must be of length less than 617 \c B_MIME_TYPE_LENGTH characters. 618 619 \note If the MIME type is not installed, it will first be installed, 620 and then the preferred app will be set. 621 622 \param signature Pointer to a pre-allocated string containing the 623 signature of the new preferred app. 624 \param verb \c app_verb value that specifies the type of access for 625 which you are setting the preferred app. Currently, the only 626 supported app verb is \c B_OPEN. 627 628 \returns \c B_OK on success or another error code on failure.*/ 629 630 \since BeOS R3 631*/ 632 633 634/*! 635 \fn status_t BMimeType::SetAttrInfo(const BMessage* info) 636 \brief Sets the description of the attributes typically associated 637 with files of the given MIME type 638 639 The attribute information is technically arbitrary, but the expected 640 format of the BMessage pointed to by the \c info parameter is as follows: 641 642 <table> 643 <tr> 644 <td><b>field name</b></td> 645 <td><b>type</b></td> 646 <td><b>element[0..n]</b></td> 647 </tr> 648 <tr> 649 <td> "attr:name"</td> 650 <td> \c B_STRING_TYPE </td> 651 <td> The name of each attribute </td> 652 </tr> 653 <tr> 654 <td> "attr:public_name"</td> 655 <td> \c B_STRING_TYPE </td> 656 <td> The human-readable name of each attribute </td> 657 </tr> 658 <tr> 659 <td> "attr:type"</td> 660 <td> \c B_INT32_TYPE </td> 661 <td> The type code for each attribute </td> 662 </tr> 663 <tr> 664 <td> "attr:viewable"</td> 665 <td> \c B_BOOL_TYPE </td> 666 <td> For each attribute: \c true if the attribute is public, 667 \c false if it's private </td> 668 </tr> 669 <tr> 670 <td> "attr:editable"</td> 671 <td> \c B_BOOL_TYPE </td> 672 <td> For each attribute: \c true if the attribute should be 673 user editable, \c false if not </td> 674 </tr> 675 </table> 676 677 The \c BMessage::what value is ignored. 678 679 \param info Pointer to a pre-allocated and properly formatted BMessage 680 containing information about the file attributes typically 681 associated with the MIME type. 682 683 \returns \c B_OK on success or another error code on failure. 684 685 \since BeOS R3 686*/ 687 688 689/*! 690 \fn status_t BMimeType::SetFileExtensions(const BMessage* extensions) 691 \brief Sets the list of filename extensions associated with the MIME type. 692 693 The MIME database associates a list of filename extensions (a character 694 string following the rightmost dot, \c ".", character in the filename) 695 with each type. These extensions can then be used to help determine the 696 type of any untyped files that may be encountered. 697 698 The list of extensions is given in a pre-allocated BMessage pointed to by 699 the \c extensions parameter. The format of the message should be as follows: 700 - The message's \c "extensions" field should contain an indexed array of 701 strings, one for each extension. The extensions are to be given 702 without the preceding \c "." character (i.e. \c "html" or \c "mp3", 703 not \c ".html" or \c ".mp3" ). 704 - The \c what member of the BMessage is ignored. 705 706 \note Any other fields present in the \c BMessage will currently be 707 retained and returned by calls to \c GetFileExtensions(); however, 708 this may change in the future, so it is recommended that you not rely 709 on this behavior, and that no other fields be present. Also, note that 710 no checking is performed to verify the \c BMessage is properly 711 formatted; it's up to you to do things right. 712 713 Finally, bear in mind that \c SetFileExtensions() clobbers the existing set 714 of extensions. If you want to augment a type's extensions, you should 715 retrieve the existing set, add the new ones, and then call 716 \c SetFileExtensions(). 717 718 \param extensions Pointer to a pre-allocated, properly formatted BMessage 719 containing the new list of file extensions to associate with this 720 MIME type. 721 722 \returns \c B_OK on success or another error code on failure. 723 724 \since BeOS R3 725*/ 726 727 728/*! 729 \fn status_t BMimeType::SetShortDescription(const char* description) 730 \brief Sets the short description field for the MIME type. 731 732 The string pointed to by \c description must be of length less than 733 \c B_MIME_TYPE_LENGTH characters. 734 735 \note If the MIME type is not installed, it will first be installed, 736 and then the short description will be set. 737 738 \param description Pointer to a pre-allocated string containing the 739 new short description. 740 741 \returns \c B_OK on success or another error code on failure. 742 743 \since BeOS R3 744*/ 745 746 747/*! 748 \fn status_t BMimeType::SetLongDescription(const char* description) 749 \brief Sets the long description field for the MIME type. 750 751 The string pointed to by \c description must be of length less than 752 \c B_MIME_TYPE_LENGTH characters. 753 754 \note If the MIME type is not installed, it will first be installed, 755 and then the long description will be set. 756 757 \param description Pointer to a pre-allocated string containing the new 758 long description 759 760 \returns \c B_OK on success or another error code on failure. 761 762 \since BeOS R3 763*/ 764 765 766/*! 767 \fn status_t BMimeType::GetInstalledSupertypes(BMessage* supertypes) 768 \brief Fetches a BMessage listing all the MIME \a supertypes currently 769 installed in the MIME database. 770 771 The types are copied into the \c "super_types" field of the passed-in 772 \c BMessage. The \c BMessage must be pre-allocated. 773 774 \param supertypes Pointer to a pre-allocated \c BMessage into which the 775 MIME \a supertypes will be copied. 776 777 \returns \c B_OK on success or another error code on failure. 778 779 \since BeOS R3 780*/ 781 782 783/*! 784 \fn status_t BMimeType::GetInstalledTypes(BMessage* types) 785 \brief Fetches a BMessage listing all the MIME types currently installed 786 in the MIME database. 787 788 The types are copied into the \c "types" field of the passed-in \c BMessage. 789 The \c BMessage must be pre-allocated. 790 791 \param types Pointer to a pre-allocated \c BMessage into which the 792 MIME types will be copied. 793 794 \returns \c B_OK on success or another error code on failure. 795 796 \since BeOS R3 797*/ 798 799 800/*! 801 \fn status_t BMimeType::GetInstalledTypes(const char* supertype, 802 BMessage* types) 803 \brief Fetches a BMessage listing all the MIME subtypes of the given 804 \a supertype currently installed in the MIME database. 805 806 The types are copied into the \c "types" field of the passed-in 807 \c BMessage. The \c BMessage must be pre-allocated. 808 809 \param supertype Pointer to a string containing the MIME \a supertype whose 810 subtypes you wish to retrieve. 811 \param types Pointer to a pre-allocated \c BMessage into which the 812 appropriate MIME subtypes will be copied. 813 814 \returns \c B_OK on success or another error code on failure. 815 816 \since BeOS R3 817*/ 818 819 820/*! 821 \fn status_t BMimeType::GetWildcardApps(BMessage* wild_ones) 822 \brief Fetches a \c BMessage containing a list of MIME signatures of 823 applications that are able to handle files of any type. 824 825 This function is the same as calling \c GetSupportingApps() on a 826 \c BMimeType object initialized to a MIME type of] 827 \c "application/octet-stream". 828 829 \param wild_ones Pointer to a pre-allocated BMessage into which 830 signatures of applications supporting files of any type 831 are copied. 832 833 \returns \c B_OK on success or another error code on failure. 834 835 \sa GetSupportingApps() for details on the format of the data returned in 836 the \c BMessage pointed to by \c wild_ones. 837 838 \since BeOS R3 839*/ 840 841 842/*! 843 \fn bool BMimeType::IsValid(const char* string) 844 \brief Returns whether the given string represents a valid MIME type. 845 846 \param string The MIME type string. 847 848 \return \c true, if the given string represents a valid MIME type. 849 850 \sa SetTo() for further information. 851 852 \since BeOS R3 853*/ 854 855 856/*! 857 \fn status_t BMimeType::GetAppHint(entry_ref* ref) const 858 \brief Fetches an \c entry_ref that serves as a hint as to where the MIME 859 type's preferred application might live 860 861 The app hint is a path that identifies the executable that should be used 862 when launching an application that has this signature. For example, when 863 Tracker needs to launch an app of type \c "application/YourAppHere", 864 it asks the database for the application hint. This hint is converted to an 865 \c entry_ref before it is passed to the caller. Of course, the path may not 866 point to an application, or it might point to an application 867 with the wrong signature (and so on); that's why this is merely a hint. 868 869 The \c entry_ref pointed to by \c ref must be pre-allocated. 870 871 \param ref Pointer to a pre-allocated \c entry_ref into which the location 872 of the app hint is copied. If the function fails, the contents of 873 the \c entry_ref are undefined. 874 875 \return A status code, B_OK on success or an error code otherwise. 876 \retval B_OK The ref was retrieved successfully. 877 \retval B_ENTRY_NOT_FOUND No app hint existed for the given \a ref. 878 \retval B_NO_INIT BMimeType was uninitialized. 879 880 \since BeOS R3 881*/ 882 883 884/*! 885 \fn status_t BMimeType::SetAppHint(const entry_ref* ref) 886 \brief Sets the app hint field for the MIME type 887 888 The app hint is a path that identifies the executable that should be used 889 when launching an application that has this signature. For example, when 890 Tracker needs to launch an app of type \c "application/YourAppHere", 891 it asks the database for the application hint. This hint is converted to an 892 \c entry_ref before it is passed to the caller. Of course, the path may not 893 point to an application, or it might point to an application with the wrong 894 signature (and so on); that's why this is merely a hint. 895 896 The \c entry_ref pointed to by \c ref must be pre-allocated. It must be a 897 valid \c entry_ref (i.e. <code>entry_ref(-1, -1, "some_file")</code> will 898 trigger an error), but it need not point to an existing file, nor need 899 it actually point to an application. That's not to say that it shouldn't; 900 such an \c entry_ref would render the app hint useless. 901 902 \param ref Pointer to a pre-allocated \c entry_ref containting the location 903 of the new app hint 904 905 \returns \c B_OK on success or another error code on failure. 906 \retval B_OK The ref was retrieved successfully. 907 \retval B_NO_INIT BMimeType was uninitialized. 908 \retval B_BAD_VALUE \a ref was \c NULL. 909 910 \since BeOS R3 911*/ 912 913 914/*! 915 \fn status_t BMimeType::GetIconForType(const char* type, BBitmap* icon, 916 icon_size which) const 917 \brief Fetches the large or mini icon used by an application of this type 918 for files of the given type. 919 920 This can be confusing, so here's how this function is intended to be used: 921 - The actual \c BMimeType object should be set to the MIME signature 922 of an application for whom you want to look up custom icons for 923 custom MIME types. 924 - The \c type parameter specifies the file type whose custom icon you 925 are fetching. 926 927 The type of the \c BMimeType object is not required to actually be a 928 subtype of \c "application/"; that is the intended use however, and calling 929 \c GetIconForType() on a non-application type will likely return 930 \c B_ENTRY_NOT_FOUND. 931 932 The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap 933 must be the proper size: \c 32x32 for the large icon, \c 16x16 for the 934 mini icon. Additionally, the bitmap must be in the \c B_CMAP8 color space 935 (8-bit color). 936 937 \param type Pointer to a pre-allocated string containing the MIME type 938 whose custom icon you wish to fetch. 939 \param icon Pointer to a pre-allocated \c BBitmap of proper size and 940 colorspace into which the icon is copied. 941 \param which Value that specifies which icon to return. Currently 942 \c B_LARGE_ICON and \c B_MINI_ICON are supported. 943 944 \returns A status code, \c B_OK on success or an error code otherwise. 945 \retval B_OK Success 946 \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the 947 given type. 948 \retval B_NO_INIT BMimeType was uninitialized. 949 950 \since BeOS R3 951*/ 952 953 954/*! 955 \fn status_t BMimeType::GetIconForType(const char* type, 956 uint8** _data, size_t* _size) const 957 \brief Fetches the vector icon used by an application of this type for 958 files of the given type. 959 960 The icon data is returned in \c data. 961 See the other GetIconForType() for more information. 962 963 \param type Pointer to a pre-allocated string containing the MIME type whose 964 custom icon you wish to fetch. 965 \param _data Pointer in which the allocated icon data is returned. You need 966 to delete the buffer when you are done with it. 967 \param _size Pointer in which the size of the allocated icon data is 968 filled out. 969 970 \returns A status code, \c B_OK on success or an error code otherwise. 971 \retval B_OK Success. 972 \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the 973 given type. 974 \retval B_NO_INIT BMimeType was uninitialized. 975 976 \since Haiku R1 977*/ 978 979 980/*! 981 \fn status_t BMimeType::SetIconForType(const char* type, 982 const BBitmap* icon, icon_size which) 983 \brief Sets the large or mini icon used by an application of this type 984 for files of the given \a type. 985 986 This can be confusing, so here's how this function is intended to be used: 987 - The actual \c BMimeType object should be set to the MIME signature of an 988 application to whom you want to assign custom icons for custom MIME types. 989 - The \c type parameter specifies the file type whose custom icon you are 990 setting. 991 992 The type of the \c BMimeType object is not required to actually be a subtype 993 of \c "application/"; that is the intended use however, and 994 application-specific icons are not expected to be present for 995 non-application types. 996 997 The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap 998 must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini 999 icon. 1000 1001 If you want to erase the current icon, pass \c NULL as the \c icon argument. 1002 1003 \param type Pointer to a pre-allocated string containing the MIME type whose 1004 custom icon you wish to set. 1005 \param icon Pointer to a pre-allocated \c BBitmap of proper size and 1006 colorspace containing the new icon, or \c NULL to clear the current 1007 icon. 1008 \param which Value that specifies which icon to update. Currently 1009 \c B_LARGE_ICON and \c B_MINI_ICON are supported. 1010 1011 \returns \c B_OK on success or another error code on failure. 1012 1013 \since BeOS R3 1014*/ 1015 1016 1017/*! 1018 \fn status_t BMimeType::SetIconForType(const char* type, const uint8* data, 1019 size_t dataSize) 1020 \brief Sets the icon used by an application of this type for files of the 1021 given \a type. 1022 1023 This can be confusing, so here's how this function is intended to be used: 1024 - The actual \c BMimeType object should be set to the MIME signature of an 1025 application to whom you want to assign custom icons for custom MIME types. 1026 - The \c type parameter specifies the file type whose custom icon you are 1027 setting. 1028 1029 The type of the \c BMimeType object is not required to actually be a subtype 1030 of \c "application/"; that is the intended use however, and 1031 application-specific icons are not expected to be present for 1032 non-application types. 1033 1034 The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap 1035 must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini 1036 icon. 1037 1038 If you want to erase the current icon, pass \c NULL as the \c icon argument. 1039 1040 \param type Pointer to a pre-allocated string containing the MIME type whose 1041 custom icon you wish to set. 1042 \param data Pointer to a pre-allocated uint8 array of the proper size to 1043 contain the new icon, or \c NULL to clear the current icon. 1044 \param dataSize The size of \a data in bytes. 1045 1046 \returns \c B_OK on success or another error code on failure. 1047 1048 \since Haiku R1 1049*/ 1050 1051 1052/*! 1053 \fn status_t BMimeType::GetSnifferRule(BString* result) const 1054 \brief Retrieves the MIME type's sniffer rule. 1055 1056 \param result Pointer to a pre-allocated BString into which the value is 1057 copied. 1058 1059 \returns A status code. 1060 \retval B_OK Everything went fine. 1061 \retval B_BAD_VALUE \c NULL \a result or uninitialized BMimeType. 1062 \retval B_ENTRY_NOT_FOUND The MIME type is not installed. 1063 \retval B_NO_INIT BMimeType was uninitialized. 1064 1065 \see SetSnifferRule() 1066 1067 \since Haiku R1 1068*/ 1069 1070 1071/*! 1072 \fn status_t BMimeType::SetSnifferRule(const char* rule) 1073 \brief Sets the MIME type's sniffer rule. 1074 1075 If the supplied \a rule is \c NULL, the MIME type's sniffer rule is 1076 unset. 1077 1078 SetSnifferRule() does also return \c B_OK, if the type is not installed, 1079 but the call will have no effect in this case. 1080 1081 \param rule The rule string, may be \c NULL. 1082 1083 \returns A status code. 1084 \retval B_OK Everything went fine. 1085 \retval B_BAD_VALUE Uninitialized BMimeType. 1086 \retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is invalid. 1087 \retval B_NO_INIT BMimeType was uninitialized. 1088 1089 \sa CheckSnifferRule() 1090 1091 \since Haiku R1 1092*/ 1093 1094 1095/*! 1096 \fn status_t BMimeType::CheckSnifferRule(const char* rule, 1097 BString* parseError) 1098 \brief Checks whether a MIME sniffer rule is valid or not. 1099 1100 A MIME sniffer rule is valid, if it is well-formed with respect to the 1101 following grammar and fulfills some further conditions listed thereafter: 1102 1103\verbatim 1104 Rule ::= LWS Priority LWS ExprList LWS 1105 ExprList ::= Expression (LWS Expression)* 1106 Expression ::= "(" LWS (PatternList | RPatternList) LWS ")" 1107 | Range LWS "(" LWS PatternList LWS ")" 1108 RPatternList ::= RPattern (LWS "|" LWS RPattern)* 1109 PatternList ::= Pattern (LWS "|" LWS Pattern)* 1110 RPattern ::= Range LWS Pattern 1111 Pattern ::= PString [ LWS "&" LWS Mask ] 1112 Range ::= "[" LWS SDecimal [LWS ":" LWS SDecimal] LWS "]" 1113 1114 Priority ::= Float 1115 Mask ::= PString 1116 PString ::= HexString | QuotedString | Octal [UnquotedString] 1117 EscapedChar [UnquotedString] 1118 HexString ::= "0x" HexPair HexPair* 1119 HexPair ::= HexChar HexChar 1120 QuotedString ::= '"' QChar QChar* '"' | "'" QChar QChar* "'" 1121 Octal ::= "\" OctChar [OctChar [OctChar]] 1122 SDecimal ::= ["+" | "-"] Decimal 1123 Decimal ::= DecChar DecChar* 1124 Float ::= Fixed [("E" | "e") Decimal] 1125 Fixed ::= SDecimal ["." [Decimal]] | [SDecimal] "." Decimal 1126 UnquotedString ::= UChar UChar* 1127 LWS ::= LWSChar* 1128 1129 LWSChar ::= LF | " " | TAB 1130 OctChar ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" 1131 DecChar ::= OctChar | "8" | "9" 1132 HexChar ::= DecChar | "a" | "b" | "c" | "d" | "e" | "A" | "B" | "C" 1133 | "D" | "E" 1134 Char :: <any character> 1135 QChar ::= <Char except "\", "&", "'" and '"'> | EscapedChar 1136 EscapedChar ::= "\" Char 1137 UChar ::= <QChar except LWSChar> 1138 1139 Conditions: 1140 (checked) 1141 - If a mask is specified for a pattern, this mask must have the same 1142 length as the pattern string. 1143 (not checked) 1144 - 0 <= Priority <= 1 1145 - 0 <= Range begin <= Range end 1146 - Rules of the form "() | () | ..." are invalid. 1147 1148 Examples: 1149 - 1.0 ('ABCD') 1150 The file must start with the string "ABCD". The priority of the rule 1151 is 1.0 (maximal). 1152 - 0.8 [0:3] ('ABCD' | 'abcd') 1153 The file must contain the string "ABCD" or "abcd" starting somewhere in 1154 the first four bytes. The rule priority is 0.8. 1155 - 0.5 ([0:3] 'ABCD' | [0:3] 'abcd' | [13] 'EFGH') 1156 The file must contain the string "ABCD" or "abcd" starting somewhere in 1157 the first four bytes or the string "EFGH" at position 13. The rule 1158 priority is 0.5. 1159 - 0.8 [0:3] ('ABCD' & 0xff00ffff | 'abcd' & 0xffff00ff) 1160 The file must contain the string "A.CD" or "ab.d" (whereas "." is an 1161 arbitrary character) starting somewhere in the first four bytes. The 1162 rule priority is 0.8. 1163 1164 Real examples: 1165 - 0.20 ([0]"//" | [0]"/\*" | [0:32]"#include" | [0:32]"#ifndef" 1166 | [0:32]"#ifdef") 1167 text/x-source-code 1168 - 0.70 ("8BPS \000\000\000\000" & 0xffffffff0000ffffffff ) 1169 image/x-photoshop 1170\endverbatim 1171 1172 \param rule The rule string. 1173 \param parseError A pointer to a pre-allocated BString into which a 1174 description of the parse error is written (if any), may be \c NULL. 1175 1176 \returns A status code. 1177 \retval B_OK The supplied sniffer rule is valid. 1178 \retval B_BAD_VALUE \c NULL \a rule. 1179 \retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is not valid. A 1180 description of the error is written to \a parseError, if supplied. 1181 \retval B_NO_INIT BMimeType was uninitialized. 1182 1183 \since Haiku R1 1184*/ 1185 1186 1187/*! 1188 \fn status_t BMimeType::GuessMimeType(const entry_ref* file, 1189 BMimeType* type) 1190 \brief Guesses a MIME type for the entry referred to by the given 1191 entry_ref. 1192 1193 This version of GuessMimeType() combines the features of the other 1194 versions: First the data of the given file are checked (sniffed). Only 1195 if the result of this operation is inconclusive, i.e. 1196 "application/octet-stream", the filename is examined for extensions. 1197 1198 \param file Pointer to the entry_ref referring to the entry. 1199 \param type Pointer to a pre-allocated BMimeType which is set to the 1200 resulting MIME type. 1201 1202 \returns A status code. 1203 \retval B_OK Everything went fine. 1204 \retval B_BAD_VALUE \c NULL \a ref or \a result. 1205 \retval B_NAME_NOT_FOUND \a ref refers to an abstract entry. 1206 \retval B_NO_INIT BMimeType was uninitialized. 1207 1208 \since Haiku R1 1209*/ 1210 1211 1212/*! 1213 \fn status_t BMimeType::GuessMimeType(const void* buffer, int32 length, 1214 BMimeType* type) 1215 \brief Guesses a MIME type for the supplied chunk of data. 1216 1217 \param buffer Pointer to the data buffer. 1218 \param length Size of the buffer in bytes. 1219 \param type Pointer to a pre-allocated BMimeType which is set to the 1220 resulting MIME type. 1221 1222 \returns A status code. 1223 \retval B_OK Everything went fine. 1224 \retval B_BAD_VALUE \c NULL \a buffer or \a result. 1225 \retval B_NO_INIT BMimeType was uninitialized. 1226 1227 \since Haiku R1 1228*/ 1229 1230 1231/*! 1232 \fn status_t BMimeType::GuessMimeType(const char* filename, BMimeType* type) 1233 \brief Guesses a MIME type for the given filename. 1234 1235 Only the filename itself is taken into consideration (in particular its 1236 name extension), not the entry it refers to. I.e. an entry with that name 1237 doesn't need to exist at all. 1238 1239 \param filename The filename. 1240 \param type Pointer to a pre-allocated BMimeType which is set to the 1241 resulting MIME type. 1242 1243 \returns A status code. 1244 \retval B_OK Everything went fine. 1245 \retval B_BAD_VALUE \c NULL \a ref or \a result. 1246 \retval B_NO_INIT BMimeType was uninitialized. 1247 1248 \since Haiku R1 1249*/ 1250 1251 1252/*! 1253 \fn status_t BMimeType::StartWatching(BMessenger target) 1254 \brief Starts monitoring the MIME database for a given target. 1255 1256 Until StopWatching() is called for the target, an update message is sent 1257 to it whenever the MIME database changes. 1258 1259 \param target A BMessenger identifying the target for the update messages. 1260 1261 \returns \c B_OK on success or another error code on failure. 1262 1263 \since BeOS R4 1264*/ 1265 1266 1267/*! 1268 \fn status_t BMimeType::StopWatching(BMessenger target) 1269 \brief Stops monitoring the MIME database for a given target (previously 1270 started via StartWatching()). 1271 1272 \param target A BMessenger identifying the target for the update messages. 1273 1274 \returns \c B_OK on success or another error code on failure. 1275 1276 \since BeOS R4 1277*/ 1278 1279 1280/*! 1281 \fn status_t BMimeType::SetType(const char* mimeType) 1282 \brief Initializes this object to the supplied MIME type. 1283 1284 \deprecated This method has the same semantics as SetTo(). 1285 Use SetTo() instead. 1286 1287 \since BeOS R3 1288*/ 1289