From d958d047936b335e0914b67f0b06c06a0dd34a71 Mon Sep 17 00:00:00 2001 From: Ingo Weinhold Date: Sun, 28 Jul 2002 13:34:44 +0000 Subject: [PATCH] Added doxygen comments for the implemented methods and fixed some smaller issues. git-svn-id: file:///srv/svn/repos/haiku/trunk/current@493 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- src/kits/app/Roster.cpp | 314 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 285 insertions(+), 29 deletions(-) diff --git a/src/kits/app/Roster.cpp b/src/kits/app/Roster.cpp index 1a0c72fec9..1a5026967f 100644 --- a/src/kits/app/Roster.cpp +++ b/src/kits/app/Roster.cpp @@ -46,6 +46,14 @@ enum { }; // _init_roster_ +/*! \brief Initializes the global be_roster variable. + + Called before the global constructors are invoked. + + \return Unknown! + + \todo Investigate what the return value means. +*/ int _init_roster_() { @@ -54,6 +62,14 @@ _init_roster_() } // _delete_roster_ +/*! \brief Deletes the global be_roster. + + Called after the global destructors are invoked. + + \return Unknown! + + \todo Investigate what the return value means. +*/ int _delete_roster_() { @@ -61,33 +77,15 @@ _delete_roster_() return 0; } -// find_message_app_info -static -status_t -find_message_app_info(BMessage *message, app_info *info) -{ - status_t error = B_OK; - const flat_app_info *flatInfo = NULL; - ssize_t size = 0; - error = message->FindData("app_info", B_REG_APP_INFO_TYPE, - (const void**)&flatInfo, &size); - if (error == B_OK) { - if (size == sizeof(flat_app_info)) { - memcpy(info, &flatInfo->info, sizeof(app_info)); - info->ref.name = NULL; - if (strlen(flatInfo->ref_name) > 0) - info->ref.set_name(flatInfo->ref_name); - } else - error = B_ERROR; - } - return error; - } - +// helper function prototypes +static status_t find_message_app_info(BMessage *message, app_info *info); /*-------------------------------------------------------------*/ /* --------- app_info Struct and Values ------------------------ */ // constructor +/*! \brief Creates an uninitialized app_info. +*/ app_info::app_info() : thread(-1), team(-1), @@ -99,6 +97,8 @@ app_info::app_info() } // destructor +/*! \brief Does nothing. +*/ app_info::~app_info() { } @@ -108,6 +108,8 @@ app_info::~app_info() /* --------- BRoster class----------------------------------- */ // constructor +/*! \brief Creates and initializes a BRoster. +*/ BRoster::BRoster() : fMess(), fMimeMess() @@ -116,6 +118,8 @@ BRoster::BRoster() } // destructor +/*! \brief Does nothing. +*/ BRoster::~BRoster() { } @@ -124,6 +128,12 @@ BRoster::~BRoster() /* Querying for apps */ // IsRunning +/*! \brief Returns whether or not an application with the supplied signature + is currently running. + \param mimeSig The app signature + \return \c true, if the supplied signature is not \c NULL and an + application with this signature is running, \c false otherwise. +*/ bool BRoster::IsRunning(const char *mimeSig) const { @@ -131,6 +141,12 @@ BRoster::IsRunning(const char *mimeSig) const } // IsRunning +/*! \brief Returns whether or not an application ran from an executable + referred to by the supplied entry_ref is currently running. + \param ref The app's entry_ref + \return \c true, if the supplied entry_ref is not \c NULL and an + application executing this file is running, \c false otherwise. +*/ bool BRoster::IsRunning(entry_ref *ref) const { @@ -138,6 +154,15 @@ BRoster::IsRunning(entry_ref *ref) const } // TeamFor +/*! \brief Returns the team ID of a currently running application with the + supplied signature. + \param mimeSig The app signature + \return + - The team ID of a running application with the supplied signature. + - \c B_BAD_VALUE: \a mimeSig is \c NULL. + - \c B_ERROR: No application with the supplied signature is currently + running. +*/ team_id BRoster::TeamFor(const char *mimeSig) const { @@ -152,6 +177,16 @@ BRoster::TeamFor(const char *mimeSig) const } // TeamFor +/*! \brief Returns the team ID of a currently running application executing + the executable referred to by the supplied entry_ref. + \param ref The app's entry_ref + \return + - The team ID of a running application executing the file referred to by + \a ref. + - \c B_BAD_VALUE: \a ref is \c NULL. + - \c B_ERROR: No application executing the file referred to by \a ref is + currently running. +*/ team_id BRoster::TeamFor(entry_ref *ref) const { @@ -166,6 +201,14 @@ BRoster::TeamFor(entry_ref *ref) const } // GetAppList +/*! \brief Returns a list of all currently running applications. + + The supplied list is not emptied before adding the team IDs of the + running applications. The list elements are team_id's, not pointers. + + \param teamIDList A pointer to a pre-allocated BList to be filled with + the team IDs. +*/ void BRoster::GetAppList(BList *teamIDList) const { @@ -188,8 +231,17 @@ BRoster::GetAppList(BList *teamIDList) const } // GetAppList -// -// The list is not emptied. +/*! \brief Returns a list of all currently running applications with the + specified signature. + + The supplied list is not emptied before adding the team IDs of the + running applications. The list elements are team_id's, not pointers. + If \a sig is \c NULL or invalid, no team IDs are added to the list. + + \param sig The app signature + \param teamIDList A pointer to a pre-allocated BList to be filled with + the team IDs. +*/ void BRoster::GetAppList(const char *sig, BList *teamIDList) const { @@ -214,6 +266,17 @@ BRoster::GetAppList(const char *sig, BList *teamIDList) const } // GetAppInfo +/*! \brief Returns the app_info of a currently running application with the + supplied signature. + \param sig The app signature + \param info A pointer to a pre-allocated app_info structure to be filled + in by this method. + \return + - \c B_OK: Everything went fine. + - \c B_BAD_VALUE: \a sig is \c NULL. + - \c B_ERROR: No application with the supplied signature is currently + running. +*/ status_t BRoster::GetAppInfo(const char *sig, app_info *info) const { @@ -237,6 +300,17 @@ BRoster::GetAppInfo(const char *sig, app_info *info) const } // GetAppInfo +/*! \brief Returns the app_info of a currently running application executing + the executable referred to by the supplied entry_ref. + \param ref The app's entry_ref + \param info A pointer to a pre-allocated app_info structure to be filled + in by this method. + \return + - \c B_OK: Everything went fine. + - \c B_BAD_VALUE: \a ref is \c NULL. + - \c B_ERROR: No application executing the file referred to by \a ref is + currently running. +*/ status_t BRoster::GetAppInfo(entry_ref *ref, app_info *info) const { @@ -260,10 +334,22 @@ BRoster::GetAppInfo(entry_ref *ref, app_info *info) const } // GetRunningAppInfo +/*! \brief Returns the app_info of a currently running application identified + by the supplied team ID. + \param team The app's team ID + \param info A pointer to a pre-allocated app_info structure to be filled + in by this method. + \return + - \c B_OK: Everything went fine. + - \c B_BAD_VALUE: \a info is \c NULL. + - \c B_BAD_TEAM_ID: \a team does not identify a running application. +*/ status_t BRoster::GetRunningAppInfo(team_id team, app_info *info) const { - status_t error = (team >= 0 && info ? B_OK : B_BAD_VALUE); + status_t error = (info ? B_OK : B_BAD_VALUE); + if (error == B_OK && team < 0) + error = B_BAD_TEAM_ID; // compose the request message BMessage request(B_REG_GET_APP_INFO); if (error == B_OK) @@ -283,6 +369,14 @@ BRoster::GetRunningAppInfo(team_id team, app_info *info) const } // GetActiveAppInfo +/*! \brief Returns the app_info of a currently active application. + \param info A pointer to a pre-allocated app_info structure to be filled + in by this method. + \return + - \c B_OK: Everything went fine. + - \c B_BAD_VALUE: \a info is \c NULL. + - \c B_ERROR: Currently no application is active. +*/ status_t BRoster::GetActiveAppInfo(app_info *info) const { @@ -348,6 +442,12 @@ BRoster::StopWatching(BMessenger target) const } // ActivateApp +/*! \brief Activates the application identified by the supplied team ID. + \param team The app's team ID + \return + - \c B_OK: Everything went fine. + - \c B_BAD_TEAM_ID: \a team does not identify a running application. +*/ status_t BRoster::ActivateApp(team_id team) const { @@ -478,10 +578,51 @@ BRoster::_StopWatching(mtarget target, BMessenger *rosterMess, uint32 what, } // AddApplication +/*! \brief (Pre-)Registers an application with the registrar. + + This methods is invoked either to register or to pre-register an + application. Full registration is requested by supplying \c true via + \a fullReg. + + A full registration requires \a mimeSig, \a ref, \a flags, \a team, + \a thread and \a port to contain valid values. No token will be return + via \a pToken. + + For a pre-registration \a mimeSig, \a ref, \a flags must be valid. + \a team and \a thread are optional and should be set to -1, if they are + unknown. If no team ID is supplied, \a pToken should be valid and, if the + the pre-registration succeeds, will be filled with a unique token assigned + by the roster. + + In both cases the registration may fail, if single/exclusive launch is + requested and an instance of the application is already running. Then + \c B_ALREADY_RUNNING is returned and the team ID of the running instance + is passed back via \a otherTeam, if supplied. + + \param mimeSig The app's signature + \param ref An entry_ref referring to the app's executable + \param flags The app flags + \param team The app's team ID + \param thread The app's main thread + \param port The app looper port + \param fullReg \c true for full, \c false for pre-registration + \param pToken A pointer to a pre-allocated uint32 into which the token + assigned by the registrar is written (may be \c NULL) + \param otherTeam A pointer to a pre-allocated team_id into which the + team ID of the already running instance of a single/exclusive + launch application is written (may be \c NULL) + \return + - \c B_OK: Everything went fine. + - \c B_ENTRY_NOT_FOUND: \a ref doesn't refer to a file. + - \c B_ALREADY_RUNNING: The application requests single/exclusive launch + and an instance is already running. + - \c B_REG_ALREADY_REGISTERED: An application with the team ID \a team + is already registered. +*/ status_t BRoster::AddApplication(const char *mimeSig, const entry_ref *ref, uint32 flags, team_id team, thread_id thread, - port_id port, bool fullReg, uint32 *_token, + port_id port, bool fullReg, uint32 *pToken, team_id *otherTeam) const { status_t error = B_OK; @@ -510,9 +651,10 @@ BRoster::AddApplication(const char *mimeSig, const entry_ref *ref, if (reply.what == B_REG_SUCCESS) { if (!fullReg && team < 0) { uint32 token; - if (request.FindInt32("token", (int32)&token) == B_OK) - *_token = token; - else + if (request.FindInt32("token", (int32)&token) == B_OK) { + if (pToken) + *pToken = token; + } else error = B_ERROR; } } else { @@ -525,18 +667,39 @@ BRoster::AddApplication(const char *mimeSig, const entry_ref *ref, } // SetSignature +/*! + \todo Really needed? +*/ void BRoster::SetSignature(team_id team, const char *mimeSig) const { } // SetThread +/*! + \todo Really needed? +*/ void BRoster::SetThread(team_id team, thread_id thread) const { } // SetThreadAndTeam +/*! \brief Sets the team and thread IDs of a pre-registered application. + + After an application has been pre-registered via AddApplication(), without + supplying a team ID, the team and thread IDs have to be set using this + method. + + \param entryToken The token identifying the application (returned by + AddApplication()) + \param thread The app's thread ID + \param team The app's team ID + \return + - \c B_OK: Everything went fine. + - \c B_REG_APP_NOT_PRE_REGISTERED: The supplied token does not identify a + pre-registered application. +*/ status_t BRoster::SetThreadAndTeam(uint32 entryToken, thread_id thread, team_id team) const @@ -561,6 +724,20 @@ BRoster::SetThreadAndTeam(uint32 entryToken, thread_id thread, } // CompleteRegistration +/*! \brief Completes the registration process for a pre-registered application. + + After an application has been pre-registered via AddApplication() and + after assigning it a team ID (via SetThreadAndTeam()) the application is + still pre-registered and must complete the registration. + + \param team The app's team ID + \param thread The app's thread ID + \param thread The app looper port + \return + - \c B_OK: Everything went fine. + - \c B_REG_APP_NOT_PRE_REGISTERED: \a team does not identify an existing + application or the identified application is already fully registered. +*/ status_t BRoster::CompleteRegistration(team_id team, thread_id thread, port_id port) const @@ -585,6 +762,17 @@ BRoster::CompleteRegistration(team_id team, thread_id thread, } // IsAppPreRegistered +/*! \brief Returns whether an application is pre-registered. + + If the application is indeed pre-registered and \a info is not \c NULL, + the methods fills in the app_info structure pointed to by \a info. + + \param ref An entry_ref referring to the app's executable + \param team The app's team ID + \param info A pointer to a pre-allocated app_info structure to be filled + in by this method (may be \c NULL) + \return \c true, if the application is pre-registered, \c false if not. +*/ bool BRoster::IsAppPreRegistered(const entry_ref *ref, team_id team, app_info *info) const @@ -615,6 +803,19 @@ BRoster::IsAppPreRegistered(const entry_ref *ref, team_id team, } // RemovePreRegApp +/*! \brief Completely unregisters a pre-registered application. + + This method can only be used to unregister applications that don't have + a team ID assigned yet. All other applications must be unregistered via + RemoveApp(). + + \param entryToken The token identifying the application (returned by + AddApplication()) + \return + - \c B_OK: Everything went fine. + - \c B_REG_APP_NOT_PRE_REGISTERED: The supplied token does not identify a + pre-registered application. +*/ status_t BRoster::RemovePreRegApp(uint32 entryToken) const { @@ -634,6 +835,18 @@ BRoster::RemovePreRegApp(uint32 entryToken) const } // RemoveApp +/*! \brief Unregisters a (pre-)registered application. + + This method must be used to unregister applications that already have + a team ID assigned, i.e. also for pre-registered application for which + SetThreadAndTeam() has already been invoked. + + \param team The app's team ID + \return + - \c B_OK: Everything went fine. + - \c B_REG_APP_NOT_REGISTERED: The supplied team ID does not identify a + (pre-)registered application. +*/ status_t BRoster::RemoveApp(team_id team) const { @@ -784,3 +997,46 @@ DBG(OUT("BRoster::InitMessengers() done\n")); const BRoster *be_roster; + +/*-----------------------------------------------------*/ +/*----- Helper functions ------------------------------*/ + +// find_message_app_info +/*! \brief Extracts an app_info from a BMessage. + + The function searchs for a field "app_info" typed B_REG_APP_INFO_TYPE + and initializes \a info with the found data. + + \param message The message + \param info A pointer to a pre-allocated app_info to be filled in with the + info found in the message. + \return + - \c B_OK: Everything went fine. + - \c B_BAD_VALUE: \c NULL \a message or \a info. + - other error codes +*/ +static +status_t +find_message_app_info(BMessage *message, app_info *info) +{ + status_t error = (message && info ? B_OK : B_BAD_VALUE); + const flat_app_info *flatInfo = NULL; + ssize_t size = 0; + // find the flat app info in the message + if (error == B_OK) { + error = message->FindData("app_info", B_REG_APP_INFO_TYPE, + (const void**)&flatInfo, &size); + } + // unflatten the flat info + if (error == B_OK) { + if (size == sizeof(flat_app_info)) { + memcpy(info, &flatInfo->info, sizeof(app_info)); + info->ref.name = NULL; + if (strlen(flatInfo->ref_name) > 0) + info->ref.set_name(flatInfo->ref_name); + } else + error = B_ERROR; + } + return error; + } +