Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added doxygen comments for the implemented methods and fixed some smaller issues.

Browse Source 
git-svn-id: file:///srv/svn/repos/haiku/trunk/current@493 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Ingo Weinhold 2002-07-28 13:34:44 +00:00
parent 3057c103f5
commit d958d04793
1 changed files with 285 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

314
src/kits/app/Roster.cpp
View File

@ -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;
}