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

@@ -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
+// helper function prototypes
-static
+static status_t find_message_app_info(BMessage *message, app_info *info);
-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;
- }
-
 
 /*-------------------------------------------------------------*/
 /* --------- 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
-//
+/*!	\brief Returns a list of all currently running applications with the
-// The list is not emptied.
+		   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)
+				if (request.FindInt32("token", (int32)&token) == B_OK) {
-					*_token = token;
+					if (pToken)
-				else
+						*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;
+ }
+