docs/user/app/Roster.dox

   1 /*
   2  * Copyright 2001-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Axel Dörfler, axeld@pinc-software.de
   7  *              John Scipione, jscipione@gmail.com
   8  *              Ingo Weinhold, ingo_weinhold@gmx.de
   9  *
  10  * Corresponds to:
  11  *              headers/os/app/Roster.h hrev47355
  12  *              src/kits/app/Roster.cpp hrev47355
  13  */
  14
  15
  16 /*!
  17         \file Roster.h
  18         \ingroup app
  19         \ingroup libbe
  20         \brief Provides the app_info struct, the BRoster class and the
  21                #be_roster global.
  22 */
  23
  24
  25 /*!
  26         \def B_SINGLE_LAUNCH
  27         \brief Single launch.
  28
  29         \since BeOS R3
  30 */
  31
  32
  33 /*!
  34         \def B_MULTIPLE_LAUNCH
  35         \brief Multiple launch.
  36
  37         \since BeOS R3
  38 */
  39
  40
  41 /*!
  42         \def B_EXCLUSIVE_LAUNCH
  43         \brief Exclusive launch.
  44
  45         \since BeOS R3
  46 */
  47
  48
  49 /*!
  50         \def B_LAUNCH_MASK
  51         \brief Bitwise and this with app_info::flags to get at the flags above.
  52
  53         \since BeOS R3
  54 */
  55
  56
  57 /*!
  58         \def B_BACKGROUND_APP
  59         \brief Background app, won't appear in Deskbar.
  60
  61         \since BeOS R3
  62 */
  63
  64
  65 /*!
  66         \def B_ARGV_ONLY
  67         \brief The application can't receive messages, information must be
  68                passed at launch through argv, typically from the command line.
  69
  70         \since BeOS R3
  71 */
  72
  73
  74 /*!
  75         \def _B_APP_INFO_RESERVED1_
  76         \brief Reserved for future use, do not use.
  77 */
  78
  79
  80 /*!
  81         \var B_REQUEST_LAUNCHED
  82         \brief \c B_SOME_APP_LAUNCHED
  83
  84         \since BeOS R3
  85 */
  86
  87
  88 /*!
  89         \var B_REQUEST_QUIT
  90         \brief \c B_SOME_APP_QUIT
  91
  92         \since BeOS R3
  93 */
  94
  95
  96 /*!
  97         \var B_REQUEST_ACTIVATED
  98         \brief \c B_SOME_APP_ACTIVATED
  99
 100         \since BeOS R3
 101 */
 102
 103
 104 /*!
 105         \struct app_info
 106         \ingroup app
 107         \ingroup libbe
 108         \brief Provides info for a running app.
 109
 110         \since BeOS R3
 111 */
 112
 113
 114 /*!
 115         \fn app_info::app_info()
 116         \brief Creates an uninitialized app_info.
 117
 118         \since BeOS R3
 119 */
 120
 121
 122 /*!
 123         \fn app_info::~app_info()
 124         \brief Does nothing.
 125
 126         \since BeOS R3
 127 */
 128
 129
 130 /*!
 131         \var app_info::thread
 132         \brief The main thread id or -1 if the application isn't running.
 133
 134         \since BeOS R3
 135 */
 136
 137
 138 /*!
 139         \var app_info::team
 140         \brief The team id or -1 if the application isn't running.
 141
 142         \since BeOS R3
 143 */
 144
 145
 146 /*!
 147         \var app_info::port
 148         \brief The main thread port, or -1 if the application isn't running.
 149
 150         \since BeOS R3
 151 */
 152
 153
 154 /*!
 155         \var app_info::flags
 156         \brief Mask of flags that determine the behavior of the application.
 157
 158         \since BeOS R3
 159 */
 160
 161
 162 /*!
 163         \var app_info::ref
 164         \brief A file ref that was executed to run the application.
 165
 166         \since BeOS R3
 167 */
 168
 169
 170 /*!
 171         \var app_info::signature[]
 172         \brief The signature that uniquely identifies the application.
 173 */
 174
 175
 176 /*!
 177         \var be_roster
 178         \brief Represents the default BRoster.
 179 */
 180
 181
 182 /*!
 183         \class BRoster
 184         \ingroup app
 185         \ingroup libbe
 186         \brief The BRoster class lets you launch apps and keeps track of apps
 187                that are running.
 188
 189         The global #be_roster object represents the default BRoster, while the
 190         app_info structure provides info for a running app.
 191
 192         \since BeOS R3
 193 */
 194
 195
 196 /*!
 197         \fn BRoster::BRoster()
 198         \brief Creates a new BRoster and sets up the connection to the roster
 199                service.
 200
 201         You should not need to call this, use the #be_roster global instead.
 202
 203         \since BeOS R3
 204 */
 205
 206
 207 /*!
 208         \fn BRoster::~BRoster()
 209         \brief Does nothing.
 210
 211         \since BeOS R3
 212 */
 213
 214
 215 /*!
 216         \name Querying
 217 */
 218
 219
 220 //! @{
 221
 222
 223 /*!
 224         \fn bool BRoster::IsRunning(const char* signature) const
 225         \brief Returns whether or not an application with the supplied signature
 226                is currently running.
 227
 228         \param signature The app \a signature.
 229
 230         \return \c true, if the supplied \a signature is not \c NULL and an
 231                 application with this \a signature is running, \c false otherwise.
 232
 233         \since BeOS R3
 234 */
 235
 236
 237 /*!
 238         \fn bool BRoster::IsRunning(entry_ref* ref) const
 239         \brief Returns whether or not an application ran from an executable
 240                referred to by the supplied entry_ref is currently running.
 241
 242         \param ref The app's entry_ref
 243         \return \c true, if the supplied entry_ref is not \c NULL and an
 244                 application executing this file is running, \c false otherwise.
 245
 246         \since BeOS R3
 247 */
 248
 249
 250 /*!
 251         \fn team_id BRoster::TeamFor(const char* signature) const
 252         \brief Returns the team ID of a currently running application with the
 253                supplied \a signature.
 254
 255         \param signature The app \a signature.
 256
 257         \return The team ID of a running application with the supplied \a signature.
 258         \retval B_BAD_VALUE \a signature is \c NULL.
 259         \retval B_ERROR No application with the supplied \a signature is currently
 260                 running.
 261
 262         \since BeOS R3
 263 */
 264
 265
 266 /*!
 267         \fn team_id BRoster::TeamFor(entry_ref* ref) const
 268         \brief Returns the team ID of a currently running application executing
 269                the executable referred to by the supplied entry_ref.
 270
 271         \param ref The app's entry_ref
 272
 273         \return The team ID of a running application executing the file referred
 274                 to by \a ref.
 275         \retval B_BAD_VALUE \a ref is \c NULL.
 276         \retval B_ERROR No application executing the file referred to by \a ref is
 277                 currently running.
 278
 279         \since BeOS R3
 280 */
 281
 282
 283 /*!
 284         \fn void BRoster::GetAppList(BList* teamIDList) const
 285         \brief Returns a list of all currently running applications.
 286
 287         The supplied list is not emptied before adding the team IDs of the
 288         running applications. The list elements are team_id's, not pointers.
 289
 290         \param teamIDList A pointer to a pre-allocated BList to be filled with
 291                    the team IDs.
 292
 293         \since BeOS R3
 294 */
 295
 296
 297 /*!
 298         \fn void BRoster::GetAppList(const char* signature,
 299                 BList* teamIDList) const
 300         \brief Returns a list of all currently running applications with the
 301                specified \a signature.
 302
 303         The supplied list is not emptied before adding the team IDs of the
 304         running applications. The list elements are team_id's, not pointers.
 305         If \a sig is \c NULL or invalid, no team IDs are added to the list.
 306
 307         \param signature The application \a signature.
 308         \param teamIDList A pointer to a pre-allocated BList to be filled with
 309                the team IDs.
 310
 311         \since BeOS R3
 312 */
 313
 314
 315 /*!
 316         \fn status_t BRoster::GetAppInfo(const char* signature,
 317                 app_info* info) const
 318         \brief Returns the app_info of a currently running application with the
 319                supplied \a signature.
 320
 321         \param signature The application \a signature.
 322         \param info A pointer to a pre-allocated app_info structure to be filled
 323                    by this method.
 324
 325         \return A status code.
 326         \retval B_OK: Everything went fine.
 327         \retval B_BAD_VALUE \a sig is \c NULL.
 328         \retval B_ERROR No application with the supplied signature is currently
 329                 running.
 330
 331         \since BeOS R3
 332 */
 333
 334
 335 /*!
 336         \fn status_t BRoster::GetAppInfo(entry_ref* ref, app_info* info) const
 337         \brief Returns the app_info of a currently running application executing
 338                the executable referred to by the supplied entry_ref.
 339
 340         \param ref The app's entry_ref
 341         \param info A pointer to a pre-allocated app_info structure to be filled
 342                    in by this method.
 343
 344         \return A status code.
 345         \retval B_OK Everything went fine.
 346         \retval B_BAD_VALUE \a ref is \c NULL.
 347         \retval B_ERROR No application executing the file referred to by \a ref was
 348                 currently running.
 349
 350         \since BeOS R3
 351 */
 352
 353
 354 /*!
 355         \fn status_t BRoster::GetRunningAppInfo(team_id team, app_info* info) const
 356         \brief Returns the app_info of a currently running application identified
 357                    by the supplied team ID.
 358
 359         \param team The app's team ID.
 360         \param info A pointer to a pre-allocated app_info structure to be filled
 361                    in by this method.
 362
 363         \return A status code.
 364         \retval B_OK Everything went fine.
 365         \retval B_BAD_VALUE \a info was \c NULL.
 366         \retval B_BAD_TEAM_ID \a team did not identify a running application.
 367
 368         \since BeOS R3
 369 */
 370
 371
 372 /*!
 373         \fn status_t BRoster::GetActiveAppInfo(app_info* info) const
 374         \brief Returns the app_info of a currently active application.
 375
 376         \param info A pointer to a pre-allocated app_info structure to be filled
 377                in by this method.
 378
 379         \return A status code.
 380         \retval B_OK Everything went fine.
 381         \retval B_BAD_VALUE \a info was \c NULL.
 382         \retval B_ERROR No application was currently active.
 383
 384         \since BeOS R3
 385 */
 386
 387
 388 /*!
 389         \fn status_t BRoster::GetActiveAppInfo(app_info* info) const
 390         \brief Returns the app_info of a currently active application.
 391
 392         \param info A pointer to a pre-allocated app_info structure to be filled
 393                    in by this method.
 394
 395         \return A status code.
 396         \retval B_OK Everything went fine.
 397         \retval B_BAD_VALUE \a info was \c NULL.
 398         \retval B_ERROR No application was currently active.
 399
 400         \since BeOS R3
 401 */
 402
 403
 404 /*!
 405         \fn status_t BRoster::FindApp(const char* mimeType, entry_ref* app) const
 406         \brief Finds an application associated with a MIME type.
 407
 408         The method gets the signature of the supplied type's preferred application
 409         and the signature of the super type's preferred application. It will also
 410         get all supporting applications for the type and super type and build a
 411         list of candiate handlers. In the case that a preferred handler is
 412         configured for the sub-type, other supporting apps will be inserted in the
 413         candidate list before the super-type preferred and supporting handlers,
 414         since it is assumed that the super type handlers are not well suited for
 415         the sub-type. The following resolving algorithm is performed on each
 416         signature of the resulting list:
 417         The MIME database is asked which executable is associated with the
 418         signature. If the database doesn't have a reference to an exectuable, the
 419         boot volume is queried for a file with the signature. If more than one file
 420         has been found, the one with the greatest version is picked, or if no file
 421         has a version info, the one with the most recent modification date. The
 422         first application from the signature list which can be successfully
 423         resolved by this algorithm is returned. Contrary to BeOS behavior, this
 424         means that if the preferred application of the provided MIME type cannot
 425         be resolved, or if it does not have a preferred application associated,
 426         the method will return other applications with direct support for the MIME
 427         type before it resorts to the preferred application or supporting
 428         applications of the super type.
 429
 430         \param mimeType The MIME type for which an application shall be found.
 431         \param app A pointer to a pre-allocated entry_ref to be filled with
 432                a reference to the found application's executable.
 433
 434         \return A status code.
 435         \retval B_OK Everything went fine.
 436         \retval B_BAD_VALUE \c NULL \a mimeType or \a app.
 437         \retval B_LAUNCH_FAILED_NO_PREFERRED_APP Neither with the supplied type nor
 438                 with its supertype (if the supplied isn't a supertype itself) a
 439                 preferred application is associated and no other supporting
 440                 applications could be identified.
 441         \retval B_LAUNCH_FAILED_APP_NOT_FOUND: The supplied type was not installed or
 442                 its preferred application could not be found.
 443         \retval B_LAUNCH_FAILED_APP_IN_TRASH: The supplied type's only supporting
 444                 application was in the trash.
 445
 446         \since BeOS R3
 447 */
 448
 449
 450 /*!
 451         \fn status_t BRoster::FindApp(entry_ref* ref, entry_ref* app) const
 452         \brief Finds an application associated with a file.
 453
 454         The method first checks, if the file has a preferred application
 455         associated with it (see BNodeInfo::GetPreferredApp()) and if so,
 456         tries to find the executable the same way FindApp(const char*, entry_ref*)
 457         does. If not, it gets the MIME type of the file and searches an
 458         application for it exactly like the first FindApp() method.
 459
 460         The type of the file is defined in a file attribute (BNodeInfo::GetType()),
 461         but if it is not set yet, the method tries to guess it via
 462         BMimeType::GuessMimeType().
 463
 464         As a special case the file may have execute permission. Then preferred
 465         application and type are ignored and an entry_ref to the file itself is
 466         returned.
 467
 468         \param ref An entry_ref referring to the file for which an application
 469                    shall be found.
 470         \param app A pointer to a pre-allocated entry_ref to be filled with
 471                    a reference to the found application's executable.
 472         \return
 473         \retval B_OK Everything went fine.
 474         \retval B_BAD_VALUE \c NULL \a mimeType or \a app.
 475         \retval B_LAUNCH_FAILED_NO_PREFERRED_APP Neither with the supplied type nor
 476                 with its supertype (if the supplied isn't a supertype itself) a
 477                 preferred application is associated.
 478         \retval B_LAUNCH_FAILED_APP_NOT_FOUND: The supplied type was not installed or
 479                 its preferred application could not be found.
 480         \retval B_LAUNCH_FAILED_APP_IN_TRASH: The supplied type's preferred
 481                 application was in the trash.
 482
 483         \since BeOS R3
 484 */
 485
 486
 487 //! @}
 488
 489
 490 /*!
 491         \name Launching, Activating, and Broadcasting
 492 */
 493
 494
 495 //! @{
 496
 497
 498 /*!
 499         \fn status_t BRoster::Broadcast(BMessage* message) const
 500         \brief Sends a message to all running applications.
 501
 502         The methods doesn't broadcast the message itself, but it asks the roster
 503         to do so. It immediatly returns after sending the request. The return
 504         value only tells about whether the request has successfully been sent.
 505
 506         The message is sent asynchronously. Replies to it go to the application.
 507         (\c be_app_messenger).
 508
 509         \param message The message to be broadcast.
 510
 511         \return A status code.
 512         \retval B_OK Everything went fine.
 513         \retval B_BAD_VALUE \c NULL \a message.
 514
 515         \since BeOS R3
 516 */
 517
 518
 519 /*!
 520         \fn status_t BRoster::Broadcast(BMessage* message, BMessenger replyTo) const
 521         \brief Sends a message to all running applications.
 522
 523         The methods doesn't broadcast the message itself, but it asks the roster
 524         to do so. It immediatly returns after sending the request. The return
 525         value only tells about whether the request has successfully been sent.
 526
 527         The message is sent asynchronously. Replies to it go to the specified
 528         target (\a replyTo).
 529
 530         \param message The message to be broadcast.
 531         \param replyTo Reply target for the message.
 532
 533         \return A status code.
 534         \retval B_OK: Everything went fine.
 535         \retval B_BAD_VALUE: \c NULL \a message.
 536
 537         \since BeOS R4
 538 */
 539
 540
 541 /*!
 542         \fn status_t BRoster::StartWatching(BMessenger target, uint32 eventMask) const
 543         \brief Adds a new roster application monitor.
 544
 545         After StartWatching() event messages will be sent to the supplied target
 546         according to the specified flags until a respective StopWatching() call.
 547
 548         \a eventMask must be a bitwise OR of one or more of the following flags:
 549         - \c B_REQUEST_LAUNCHED: A \c B_SOME_APP_LAUNCHED is sent, whenever an
 550           application has been launched.
 551         - \c B_REQUEST_QUIT: A \c B_SOME_APP_QUIT is sent, whenever an
 552           application has quit.
 553         - \c B_REQUEST_ACTIVATED: A \c B_SOME_APP_ACTIVATED is sent, whenever an
 554           application has been activated.
 555
 556         All event messages contain the following fields supplying more information
 557         about the concerned application:
 558         - \c "be:signature", \c B_STRING_TYPE: The signature of the application.
 559         - \c "be:team", \c B_INT32_TYPE: The team ID of the application
 560           (\c team_id).
 561         - \c "be:thread", \c B_INT32_TYPE: The ID of the application's main thread
 562           (\c thread_id).
 563         - \c "be:flags", \c B_INT32_TYPE: The application flags (\c uint32).
 564         - \c "be:ref", \c B_REF_TYPE: An entry_ref referring to the application's
 565           executable.
 566
 567         A second call to StartWatching() with the same \a target simply sets
 568         the new \a eventMask. The messages won't be sent twice to the target.
 569
 570         \param target The target the event messages shall be sent to.
 571         \param eventMask Specifies the events the caller is interested in.
 572
 573         \return \c B_OK if everything went fine or an error code, if some error
 574                 occurred.
 575
 576         \since BeOS R4
 577 */
 578
 579
 580 /*!
 581         \fn status_t BRoster::StopWatching(BMessenger target) const
 582         \brief Removes a roster application monitor added with StartWatching().
 583
 584         \param target The target that shall not longer receive any event messages.
 585
 586         \return A status code.
 587         \retval B_OK Everything went fine.
 588         \retval B_BAD_VALUE No application monitor has been associated with the
 589                 specified \a target before.
 590
 591         \since BeOS R4
 592 */
 593
 594
 595 /*!
 596         \fn status_t BRoster::ActivateApp(team_id team) const
 597         \brief Activates the application identified by the supplied team ID.
 598
 599         \param team The app's team ID
 600
 601         \return A status code.
 602         \retval B_OK Everything went fine.
 603         \retval B_BAD_TEAM_ID \a team does not identify a running application.
 604
 605         \since BeOS R3
 606 */
 607
 608
 609 /*!
 610         \fn status_t BRoster::Launch(const char* mimeType,
 611                 BMessage* initialMessage, team_id* appTeam) const
 612         \brief Launches the application associated with the supplied MIME type.
 613
 614         The application to be started is searched the same way FindApp() does it.
 615
 616         \a initialMessage is a message to be sent to the application "on launch",
 617         i.e. before ReadyToRun() is invoked on the BApplication object. The
 618         caller retains ownership of the supplied BMessage. In case the method
 619         fails with \c B_ALREADY_RUNNING the message is delivered to the already
 620         running instance.
 621
 622         \param mimeType MIME type for which the application shall be launched.
 623         \param initialMessage Optional message to be sent to the application
 624                "on launch". May be \c NULL.
 625         \param appTeam Pointer to a pre-allocated team_id variable to be set to
 626                the team ID of the launched application.
 627
 628         \return A status code.
 629         \retval B_OK Everything went fine.
 630         \retval B_BAD_VALUE \c NULL \a mimeType
 631         \retval B_LAUNCH_FAILED_NO_PREFERRED_APP Neither with the supplied type
 632                 nor with its supertype (if the supplied isn't a supertype itself)
 633                 a preferred application is associated.
 634         \retval B_LAUNCH_FAILED_APP_NOT_FOUND The supplied type is not installed
 635                 or its preferred application could not be found.
 636         \retval B_LAUNCH_FAILED_APP_IN_TRASH The supplied type's preferred
 637                 application was in the trash.
 638         \retval B_LAUNCH_FAILED_EXECUTABLE The found application was not
 639                 executable.
 640         \retval B_ALREADY_RUNNING The application's app flags specify
 641         \retval B_SINGLE_LAUNCH or \c B_EXCLUSIVE_LAUNCH and the application (the very
 642                 same (single) or at least one with the same signature (exclusive)) is
 643                 already running.
 644
 645         \since BeOS R3
 646 */
 647
 648
 649 /*!
 650         \fn status_t BRoster::Launch(const char* mimeType, BList* messageList,
 651                 team_id* appTeam) const
 652         \brief Launches the application associated with the supplied MIME type.
 653
 654         The application to be started is searched the same way FindApp() does it.
 655
 656         \a messageList contains messages to be sent to the application
 657         "on launch", i.e. before ReadyToRun() is invoked on the BApplication
 658         object. The caller retains ownership of the supplied BList and the
 659         contained BMessages. In case the method fails with \c B_ALREADY_RUNNING
 660         the messages are delivered to the already running instance.
 661
 662         \param mimeType MIME type for which the application shall be launched.
 663         \param messageList Optional list of messages to be sent to the application
 664                "on launch". May be \c NULL.
 665         \param appTeam Pointer to a pre-allocated team_id variable to be set to
 666                the team ID of the launched application.
 667
 668         \return A status code.
 669         \retval B_OK Everything went fine.
 670         \retval B_BAD_VALUE \c NULL \a mimeType
 671         \retval B_LAUNCH_FAILED_NO_PREFERRED_APP Neither with the supplied type
 672                 nor with its supertype (if the supplied isn't a supertype itself)
 673                 a preferred application is associated.
 674         \retval B_LAUNCH_FAILED_APP_NOT_FOUND The supplied type is not installed
 675                 or its preferred application could not be found.
 676         \retval B_LAUNCH_FAILED_APP_IN_TRASH The supplied type's preferred
 677                 application was in the trash.
 678         \retval B_LAUNCH_FAILED_EXECUTABLE The found application was not
 679                 executable.
 680
 681         \since BeOS R3
 682 */
 683
 684
 685 /*!
 686         \fn status_t BRoster::Launch(const char* mimeType, int argc,
 687                 const char* const* args, team_id* appTeam) const
 688         \brief Launches the application associated with the supplied MIME type.
 689
 690         The application to be started is searched the same way FindApp() does it.
 691
 692         The supplied \a argc and \a args are (if containing at least one argument)
 693         put into a \c B_ARGV_RECEIVED message and sent to the launched application
 694         "on launch". The caller retains ownership of the supplied \a args.
 695         In case the method fails with \c B_ALREADY_RUNNING the message is
 696         delivered to the already running instance.
 697
 698         \param mimeType MIME type for which the application shall be launched.
 699         \param argc Specifies the number of elements in \a args.
 700         \param args An array of C-strings to be sent as B_ARGV_RECEIVED messaged
 701                    to the launched application.
 702         \param appTeam Pointer to a pre-allocated team_id variable to be set to
 703                    the team ID of the launched application.
 704
 705         \return A status code.
 706         \retval B_OK Everything went fine.
 707         \retval B_BAD_VALUE \c NULL \a mimeType
 708         \retval B_LAUNCH_FAILED_NO_PREFERRED_APP Neither with the supplied type
 709                 nor with its supertype (if the supplied isn't a supertype itself)
 710                 a preferred application is associated.
 711         \retval B_LAUNCH_FAILED_APP_NOT_FOUND The supplied type is not installed
 712                 or its preferred application could not be found.
 713         \retval B_LAUNCH_FAILED_APP_IN_TRASH The supplied type's preferred
 714                 application was in the trash.
 715         \retval B_LAUNCH_FAILED_EXECUTABLE The found application was not
 716                 executable.
 717
 718         \since BeOS R3
 719 */
 720
 721
 722 /*!
 723         \fn status_t BRoster::Launch(const entry_ref* ref,
 724                 const BMessage* initialMessage, team_id* appTeam) const
 725         \brief Launches the application associated with the entry referred to by
 726                    the supplied entry_ref.
 727
 728         The application to be started is searched the same way FindApp() does it.
 729
 730         If \a ref does refer to an application executable, that application is
 731         launched. Otherwise the respective application is searched and launched,
 732         and \a ref is sent to it in a \c B_REFS_RECEIVED message.
 733
 734         \a initialMessage is a message to be sent to the application "on launch",
 735         i.e. before ReadyToRun() is invoked on the BApplication object. The
 736         caller retains ownership of the supplied BMessage. In case the method
 737         fails with \c B_ALREADY_RUNNING the message is delivered to the already
 738         running instance. The same applies to the \c B_REFS_RECEIVED message.
 739
 740         \param ref entry_ref referring to the file for which an application shall
 741                    be launched.
 742         \param initialMessage Optional message to be sent to the application
 743                    "on launch". May be \c NULL.
 744         \param appTeam Pointer to a pre-allocated team_id variable to be set to
 745                    the team ID of the launched application.
 746
 747         \return A status code.
 748         \retval B_OK Everything went fine.
 749         \retval B_BAD_VALUE \c NULL \a mimeType
 750         \retval B_LAUNCH_FAILED_NO_PREFERRED_APP Neither with the supplied type
 751                 nor with its supertype (if the supplied isn't a supertype itself)
 752                 a preferred application is associated.
 753         \retval B_LAUNCH_FAILED_APP_NOT_FOUND The supplied type is not installed
 754                 or its preferred application could not be found.
 755         \retval B_LAUNCH_FAILED_APP_IN_TRASH The supplied type's preferred
 756                 application was in the trash.
 757         \retval B_LAUNCH_FAILED_EXECUTABLE The found application was not
 758                 executable.
 759         \retval B_ALREADY_RUNNING: The application's app flags specify
 760                 \c B_SINGLE_LAUNCH or \c B_EXCLUSIVE_LAUNCH and the application
 761                 (the very same (single) or at least one with the same signature
 762                 (exclusive)) was already running.
 763
 764         \since BeOS R3
 765 */
 766
 767
 768 /*!
 769         \fn status_t BRoster::Launch(const entry_ref* ref, const BList* messageList,
 770                 team_id* appTeam) const
 771         \brief Launches the application associated with the entry referred to by
 772                    the supplied entry_ref.
 773
 774         The application to be started is searched the same way FindApp() does it.
 775
 776         If \a ref does refer to an application executable, that application is
 777         launched. Otherwise the respective application is searched and launched,
 778         and \a ref is sent to it in a \c B_REFS_RECEIVED message.
 779
 780         \a messageList contains messages to be sent to the application
 781         "on launch", i.e. before ReadyToRun() is invoked on the BApplication
 782         object. The caller retains ownership of the supplied BList and the
 783         contained BMessages. In case the method fails with \c B_ALREADY_RUNNING
 784         the messages are delivered to the already running instance. The same
 785         applies to the \c B_REFS_RECEIVED message.
 786
 787         \param ref entry_ref referring to the file for which an application shall
 788                    be launched.
 789         \param messageList Optional list of messages to be sent to the application
 790                    "on launch". May be \c NULL.
 791         \param appTeam Pointer to a pre-allocated team_id variable to be set to
 792                    the team ID of the launched application.
 793
 794         \return A status code.
 795         \retval B_OK Everything went fine.
 796         \retval B_BAD_VALUE \c NULL \a mimeType
 797         \retval B_LAUNCH_FAILED_NO_PREFERRED_APP Neither with the supplied type
 798                 nor with its supertype (if the supplied isn't a supertype itself)
 799                 a preferred application is associated.
 800         \retval B_LAUNCH_FAILED_APP_NOT_FOUND The supplied type is not installed
 801                 or its preferred application could not be found.
 802         \retval B_LAUNCH_FAILED_APP_IN_TRASH The supplied type's preferred
 803                 application was in the trash.
 804         \retval B_LAUNCH_FAILED_EXECUTABLE The found application was not
 805                 executable.
 806
 807         \since BeOS R3
 808 */
 809
 810
 811 /*!
 812         \fn status_t BRoster::Launch(const entry_ref* ref, int argc,
 813                 const char* const* args, team_id* appTeam) const
 814         \brief Launches the application associated with the entry referred to by
 815                    the supplied entry_ref.
 816
 817         The application to be started is searched the same way FindApp() does it.
 818
 819         If \a ref does refer to an application executable, that application is
 820         launched. Otherwise the respective application is searched and launched,
 821         and \a ref is sent to it in a \c B_REFS_RECEIVED message, unless other
 822         arguments are passed via \a argc and \a args -- then the entry_ref is
 823         converted into a path (C-string) and added to the argument vector.
 824
 825         The supplied \a argc and \a args are (if containing at least one argument)
 826         put into a \c B_ARGV_RECEIVED message and sent to the launched application
 827         "on launch". The caller retains ownership of the supplied \a args.
 828         In case the method fails with \c B_ALREADY_RUNNING the message is
 829         delivered to the already running instance. The same applies to the
 830         \c B_REFS_RECEIVED message, if no arguments are supplied via \a argc and
 831         \a args.
 832
 833         \param ref entry_ref referring to the file for which an application shall
 834                    be launched.
 835         \param argc Specifies the number of elements in \a args.
 836         \param args An array of C-strings to be sent as B_ARGV_RECEIVED messaged
 837                    to the launched application.
 838         \param appTeam Pointer to a pre-allocated team_id variable to be set to
 839                    the team ID of the launched application.
 840
 841         \return A status code.
 842         \retval B_OK Everything went fine.
 843         \retval B_BAD_VALUE \c NULL \a mimeType
 844         \retval B_LAUNCH_FAILED_NO_PREFERRED_APP Neither with the supplied type
 845                 nor with its supertype (if the supplied isn't a supertype itself)
 846                 a preferred application is associated.
 847         \retval B_LAUNCH_FAILED_APP_NOT_FOUND The supplied type is not installed
 848                 or its preferred application could not be found.
 849         \retval B_LAUNCH_FAILED_APP_IN_TRASH The supplied type's preferred
 850                 application was in the trash.
 851         \retval B_LAUNCH_FAILED_EXECUTABLE The found application was not
 852                 executable.
 853
 854         \since BeOS R3
 855 */
 856
 857
 858 //! @}
 859
 860
 861 /*!
 862         \name Recent Information
 863 */
 864
 865
 866 //! @{
 867
 868
 869 /*!
 870         \fn void BRoster::GetRecentDocuments(BMessage* refList, int32 maxCount,
 871                 const char* fileType, const char* signature) const
 872         \brief Returns a list of the most recently used documents.
 873
 874         \param refList Filled out with information about recently used documents.
 875         \param maxCount The maximum number of documents to get information on.
 876         \param fileType Filter documents by MIME-type string.
 877         \param signature Get info only on documents that were used by a
 878                specific application.
 879
 880         \since BeOS R5
 881 */
 882
 883
 884 /*!
 885         \fn void BRoster::GetRecentDocuments(BMessage* refList, int32 maxCount,
 886                 const char* fileTypes[], int32 fileTypesCount,
 887                 const char* signature) const
 888         \brief Returns a list of the most recently used documents.
 889
 890         \param refList Filled out with information about recently used documents.
 891         \param maxCount The maximum number of documents to get information on.
 892         \param fileTypes Filter documents by and array of MIME-type string.
 893         \param fileTypesCount The number of MIME-types in \a fileType.
 894         \param signature Get info only on documents that were used by a
 895                specific application.
 896
 897         \since BeOS R5
 898 */
 899
 900
 901 /*!
 902         \fn void BRoster::GetRecentFolders(BMessage* refList, int32 maxCount,
 903                 const char* signature) const
 904         \brief Returns a list of recently accessed folders.
 905
 906         \param refList Filled out with information about recently used folders.
 907         \param maxCount The maximum number of folders to get information on.
 908         \param signature Get info only on folders that were used by a
 909                specific application.
 910
 911         \since BeOS R5
 912 */
 913
 914
 915 /*!
 916         \fn void BRoster::GetRecentApps(BMessage* refList, int32 maxCount) const
 917         \brief Returns a list of the most recently launched applications.
 918
 919         \param refList Filled out with information about recently used apps.
 920         \param maxCount The maximum number of apps to get information on.
 921
 922         \since BeOS R5
 923 */
 924
 925
 926 /*!
 927         \fn void BRoster::AddToRecentDocuments(const entry_ref* document,
 928                 const char* signature) const
 929         \brief Adds the \a document to the list of recent documents.
 930
 931         \param document The \a document to add.
 932         \param signature To record that a specific application
 933                used the document.
 934
 935         \since BeOS R5
 936 */
 937
 938
 939 /*!
 940         \fn void BRoster::AddToRecentFolders(const entry_ref* folder,
 941                 const char* signature) const
 942         \brief Adds \a folder to the list of recent folders.
 943
 944         \param folder The \a folder to add.
 945         \param signature To record that a specific application
 946                used the folder.
 947
 948         \since BeOS R5
 949 */
 950
 951
 952 //! @}