diff --git a/include/am/ActivityManagerService.h b/include/am/ActivityManagerService.h index 9831578..17048cd 100644 --- a/include/am/ActivityManagerService.h +++ b/include/am/ActivityManagerService.h @@ -38,49 +38,202 @@ using os::app::IServiceConnection; class ActivityManagerInner; +/** + * @class ActivityManagerService + * @brief Service that manages activities and services in the system. + */ class ActivityManagerService : public os::am::BnActivityManager { public: + /** + * @brief Constructor to initialize the ActivityManagerService. + * + * @param[in] looper The event loop associated with the service. + */ ActivityManagerService(uv_loop_t* looper); + /** + * @brief Destructor for the ActivityManagerService. + */ ~ActivityManagerService(); - /***binder api***/ + /** + * @brief Attaches an application to the service. + * + * @param[in] app The application thread to be attached. + * @param[in] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status attachApplication(const sp& app, int32_t* ret) override; - + /** + * @brief Starts an activity. + * + * @param[in] token The token associated with the activity. + * @param[in] intent The intent used to start the activity. + * @param[in] code The request code associated with the activity. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status startActivity(const sp& token, const Intent& intent, int32_t code, int32_t* ret) override; + /** + * @brief Stops an activity. + * + * @param[in] intent The intent used to stop the activity. + * @param[in] resultCode The result code to return when stopping the activity. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status stopActivity(const Intent& intent, int32_t resultCode, int32_t* ret) override; + /** + * @brief Stops an application. + * + * @param[in] token The token associated with the application to stop. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status stopApplication(const sp& token, int32_t* ret) override; - + /** + * @brief Finishes an activity. + * + * @param[in] token The token associated with the activity. + * @param[in] resultCode The result code of the activity. + * @param[in] resultData Optional data to be passed as the result. + * @param[out] ret Output parameter indicating whether the operation was successful. + * @return Status The status of the operation. + */ Status finishActivity(const sp& token, int32_t resultCode, const std::optional& resultData, bool* ret) override; + /** + * @brief Moves an activity task to the background. + * + * @param[in] token The token associated with the activity. + * @param[in] nonRoot Whether the activity is not the root activity. + * @param[out] ret Output parameter indicating whether the operation was successful. + * @return The status of the operation. + */ Status moveActivityTaskToBackground(const sp& token, bool nonRoot, bool* ret) override; - + /** + * @brief Reports the status of an activity. + * + * @param[in] token The token associated with the activity. + * @param[in] status The status to report for the activity. + * @return The status of the operation. + */ Status reportActivityStatus(const sp& token, int32_t status) override; - + /** + * @brief Starts a service. + * + * @param[in] intent The intent used to start the service. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status startService(const Intent& intent, int32_t* ret) override; + /** + * @brief Stops a service. + * + * @param[in] intent The intent used to stop the service. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status stopService(const Intent& intent, int32_t* ret) override; + /** + * @brief Stops a service by its token. + * + * @param[in] token The token associated with the service to stop. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status stopServiceByToken(const sp& token, int32_t* ret) override; + /** + * @brief Reports the status of a service. + * + * @param[in] token The token associated with the service. + * @param[in] status The status to report for the service. + * @return The status of the operation. + */ Status reportServiceStatus(const sp& token, int32_t status) override; - + /** + * @brief Binds a service. + * + * @param[in] token The token associated with the service. + * @param[in] intent The intent used to bind the service. + * @param[in] conn The service connection used to manage the connection. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status bindService(const sp& token, const Intent& intent, const sp& conn, int32_t* ret) override; + /** + * @brief Unbinds a service. + * + * @param[in] conn The service connection used to manage the connection. + * @return The status of the operation. + */ Status unbindService(const sp& conn) override; + /** + * @brief Publishes a service. + * + * @param[in] token The token associated with the service. + * @param[in] service The binder object associated with the service. + * @return The status of the operation. + */ Status publishService(const sp& token, const sp& service) override; - + /** + * @brief Posts an intent to be processed by the system. + * + * @param[in] intent The intent to be posted. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status postIntent(const Intent& intent, int32_t* ret) override; + /** + * @brief Sends a broadcast intent. + * + * @param[in] intent The broadcast intent to send. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status sendBroadcast(const Intent& intent, int32_t* ret) override; + /** + * @brief Registers a receiver for a specific action. + * + * @param[in] action The action to register for. + * @param[in] receiver The receiver to be registered. + * @param[out] ret Output parameter for the result of the operation. + * @return The status of the operation. + */ Status registerReceiver(const std::string& action, const sp& receiver, int32_t* ret) override; + /** + * @brief Unregisters a previously registered receiver. + * + * @param[in] receiver The receiver to be unregistered. + * @return The status of the operation. + */ Status unregisterReceiver(const sp& receiver) override; - + /** + * @brief Dumps the current state of the ActivityManagerService. + * + * @param[in] fd The file descriptor to write the dump to. + * @param[in] args The arguments to filter the dump. + * @return The status of the dump operation. + */ android::status_t dump(int fd, const android::Vector& args) override; - // The service is ready to start and the application can be launched + /** + * @brief Marks the service as ready for operation. + * + * This method is called when the service is ready to start and the application can be launched. + */ void systemReady(); + /** + * @brief Sets the window manager for the system. + * + * @param[in] wm The window manager service to set. + */ void setWindowManager(sp<::os::wm::IWindowManager> wm); private: - ActivityManagerInner* mInner; + ActivityManagerInner* mInner; /**< Internal implementation for managing activity operations. */ }; } // namespace am diff --git a/include/app/Activity.h b/include/app/Activity.h index 918d225..054f67a 100644 --- a/include/app/Activity.h +++ b/include/app/Activity.h @@ -30,30 +30,105 @@ namespace app { class ActivityClientRecord; class ApplicationThreadStub; +/** + * @class Activity + * @brief Represents a crucial component of an Android app. + * + * Activity is a component used to represent a user interface in Android. + */ class Activity : public ContextWrapper { public: + /** + * @brief Default constructor for Activity. + */ Activity() = default; + /** + * @brief Default Destructor for Activity. + */ virtual ~Activity() = default; - + /** + * @brief Lifecycle method called when the Activity is created. + */ virtual void onCreate() = 0; + /** + * @brief Lifecycle method called when the Activity becomes visible and starts interacting with + * the user. + */ virtual void onStart() = 0; + /** + * @brief Lifecycle method called when the Activity is fully visible and interactive. + */ virtual void onResume() = 0; + /** + * @brief Lifecycle method called when the Activity is paused and no longer in the foreground. + */ virtual void onPause() = 0; + /** + * @brief Lifecycle method called when the Activity is no longer visible and stops interacting + * with the user. + */ virtual void onStop() = 0; + /** + * @brief Lifecycle method called when the Activity is about to be destroyed. + */ virtual void onDestroy() = 0; + /** + * @brief Called when the Activity is restarted after being stopped. + */ virtual void onRestart(){}; + /** + * @brief Called when the Activity receives a new Intent. + * + * @param[in] intent The new Intent that was received. + */ virtual void onNewIntent(const Intent& intent){}; + /** + * @brief Called when the Activity receives a result from another Activity. + * + * @param[in] requestCode The code identifying the request. + * @param[in] resultCode The result code of the operation. + * @param[in] resultData The data returned from the operation. + */ virtual void onActivityResult(const int requestCode, const int resultCode, const Intent& resultData){}; + /** + * @brief Called when the back button is pressed. + */ virtual void onBackPressed() { finish(); } + /** + * @brief Called when the Activity receives an Intent during its lifecycle. + * + * @param[in] intent The Intent that was received. + */ virtual void onReceiveIntent(const Intent& intent){}; + /** + * @brief Sets the result for the Activity and finishes it. + * + * @param[in] resultCode The result code indicating the outcome + * @param[in] resultData The data to return to the calling Activity. + */ void setResult(const int resultCode, const std::shared_ptr& resultData); + /** + * @brief Finishes the Activity and removes it from the stack. + */ void finish(); + /** + * @brief Moves the Activity to the background. + * + * @param[in] nonRoot Whether to consider root status when moving to the background. Default is + * true. + * @return True if the Activity was successfully moved to the background, false otherwise. + */ bool moveToBackground(bool nonRoot = true); + /** + * @brief Gets the window associated with the Activity. + * + * @return A shared pointer to the BaseWindow object associated with this Activity. + */ std::shared_ptr<::os::wm::BaseWindow> getWindow() { return mWindow; } @@ -61,18 +136,54 @@ class Activity : public ContextWrapper { private: friend class ActivityClientRecord; friend class ApplicationThreadStub; + /** + * @brief Attaches the Activity to a given Context. + * + * @param[in] context The Context to attach the Activity to. + * @return An integer representing the result of the attachment process. + */ int attach(std::shared_ptr context); + /** + * @brief Performs the creation lifecycle step for the Activity. + * + * @return True if the creation was successful, false otherwise. + */ bool performCreate(); + /** + * @brief Performs the start lifecycle step for the Activity. + * + * @return True if the start was successful, false otherwise. + */ bool performStart(); + /** + * @brief Performs the resume lifecycle step for the Activity. + * + * @return True if the resume was successful, false otherwise. + */ bool performResume(); + /** + * @brief Performs the pause lifecycle step for the Activity. + * + * @return True if the pause was successful, false otherwise. + */ bool performPause(); + /** + * @brief Performs the stop lifecycle step for the Activity. + * + * @return True if the stop was successful, false otherwise. + */ bool performStop(); + /** + * @brief Performs the destroy lifecycle step for the Activity. + * + * @return True if the destroy was successful, false otherwise. + */ bool performDestroy(); private: - int mResultCode; - std::shared_ptr mResultData; - std::shared_ptr<::os::wm::BaseWindow> mWindow; + int mResultCode; /**< The result code returned from the activity. */ + std::shared_ptr mResultData; /**< The result data returned from the activity. */ + std::shared_ptr<::os::wm::BaseWindow> mWindow; /**< The window associated with this activity. */ }; } // namespace app diff --git a/include/app/ActivityManager.h b/include/app/ActivityManager.h index a383966..243ec17 100644 --- a/include/app/ActivityManager.h +++ b/include/app/ActivityManager.h @@ -35,61 +35,194 @@ using os::app::Intent; using os::app::IServiceConnection; using std::string; +/** + * @class ActivityManager + * @brief Manages activities and services within the Android application. + * + * This class provides various methods to manage the lifecycle of activities, + * services, and broadcast receivers, as well as communicating with the activity + * and service managers in the system. + */ class ActivityManager { public: + /** + * @brief Default constructor for ActivityManager. + */ ActivityManager() = default; + /** + * @brief Default destructor for ActivityManager. + */ ~ActivityManager() = default; + /** + * @brief Get the name of the activity manager. + * + * @return The name of the activity manager as a constant C-string. + */ static inline const char* name() { return "activity"; } /** define constant macro */ - static const int NO_REQUEST = -1; - static const int RESULT_OK = 0; - static const int RESULT_CANCEL = -1; + static const int NO_REQUEST = -1; /**< No request code. */ + static const int RESULT_OK = 0; /**< Result code indicating success. */ + static const int RESULT_CANCEL = -1; /**< Cancelled result code. */ /** The status is part of AMS inside */ enum { - CREATED = 1, - STARTED = 3, - RESUMED = 5, - PAUSED = 7, - STOPPED = 9, - DESTROYED = 11, + CREATED = 1, /**< Activity has been created. */ + STARTED = 3, /**< Activity has started. */ + RESUMED = 5, /**< Activity has resumed. */ + PAUSED = 7, /**< Activity has paused. */ + STOPPED = 9, /**< Activity has stopped. */ + DESTROYED = 11, /**< Activity has been destroyed. */ }; + /** + * @brief Attach an application thread to the activity manager. + * + * @param[in] app The application thread to attach. + * @return An integer representing the status of the operation. + */ int32_t attachApplication(const sp& app); + /** + * @brief Start an activity. + * + * @param[in] token The token for the activity. + * @param[in] intent The intent to start the activity. + * @param [in] requestCode The request code for the activity. + * @return The status of the operation. + */ int32_t startActivity(const sp& token, const Intent& intent, int32_t requestCode); + /** + * @brief Stop an activity. + * + * @param[in] intent The intent representing the activity to be stopped. + * @param[in] resultCode The result code for the activity stop. + * @return The status of the operation. + */ int32_t stopActivity(const Intent& intent, int32_t resultCode); + /** + * @brief Stop a running application. + * + * @param[in] token The token of the application to stop. + * @return The status of the operation. + */ int32_t stopApplication(const sp& token); - + /** + * @brief Finish the specified activity. + * + * @param[in] token The token of the activity to finish. + * @param[in] resultCode The result code of the activity. + * @param[in] resultData The data associated with the result. + * @return True if the activity was successfully finished, false otherwise. + */ bool finishActivity(const sp& token, int32_t resultCode, const std::shared_ptr& resultData); - + /** + * @brief Move the activity task to the background. + * + * @param[in] token The token of the activity. + * @param[in] nonRoot If true, only non-root activities will be moved to the background. + * @return The status of the operation. + */ bool moveActivityTaskToBackground(const sp& token, bool nonRoot); - + /** + * @brief Report the status of an activity. + * + * @param[in] token The token of the activity. + * @param[in] status The status to report. + */ void reportActivityStatus(const sp& token, int32_t status); - + /** + * @brief Start a service. + * + * @param[in] intent The intent to start the service. + * @return The status of the operation. + */ int32_t startService(const Intent& intent); + /** + * @brief Stop a service. + * + * @param[in] intent The intent associated with the service. + * @return The status of the operation. + */ int32_t stopService(const Intent& intent); + /** + * @brief Report the status of a service. + * + * @param[in] token The token of the service. + * @param[in] status The status to report. + */ void reportServiceStatus(const sp& token, int32_t status); + /** + * @brief Bind a service. + * + * @param[in] token The token for the service. + * @param[in] intent The intent to bind the service. + * @param[in] conn The service connection. + * @return The status of the operation. + */ int32_t bindService(const sp& token, const Intent& intent, const sp& conn); + /** + * @brief Unbind a service. + * + * @param[in] conn The service connection to unbind. + */ void unbindService(const sp& conn); + /** + * @brief Publish a service. + * + * @param[in] token The token of the service. + * @param[in] serviceHandler The handler for the service. + */ void publishService(const sp& token, const sp& serviceHandler); + /** + * @brief Stop a service by its token. + * + * @param[in] token The token of the service to stop. + * @return The status of the operation. + */ int32_t stopServiceByToken(const sp& token); - + /** + * @brief Post an intent to the activity manager. + * + * @param[in] intent The intent to post. + * @return The status of the operation. + */ int32_t postIntent(const Intent& intent); + /** + * @brief Send a broadcast. + * + * @param[in] intent The intent for the broadcast. + * @return The status of the operation. + */ int32_t sendBroadcast(const Intent& intent); + /** + * @brief Register a receiver for a specific action. + * + * @param[in] action The action to listen for. + * @param[in] receiver The receiver to register. + * @return The status of the operation. + */ int32_t registerReceiver(const std::string& action, const sp& receiver); + /** + * @brief Unregister a broadcast receiver. + * + * @param[in] receiver The receiver to unregister. + */ void unregisterReceiver(const sp& receiver); - + /** + * @brief Get the activity manager service instance. + * + * @return A reference to the activity manager service. + */ sp getService(); private: - std::mutex mLock; - sp mService; + std::mutex mLock; /**< Mutex for thread safety. */ + sp mService; /**< The activity manager service instance. */ }; } // namespace app diff --git a/include/app/AppMain.h b/include/app/AppMain.h index acde41d..c387769 100644 --- a/include/app/AppMain.h +++ b/include/app/AppMain.h @@ -23,6 +23,18 @@ * #define APPLICATION MyApplication * #include */ + +/** + * @brief The entry point for the application. + * + * This function initializes the application and runs the main event loop + * using the ApplicationThread class. It processes command line arguments + * and starts the application thread to handle the main loop. + * + * @param[in] argc The number of command line arguments. + * @param[in] argv The array of command line arguments. + * @return An integer status code, where 0 indicates successful execution. + */ extern "C" int main(int argc, char **argv) { APPLICATION app; os::app::ApplicationThread appThread(&app); diff --git a/include/app/Application.h b/include/app/Application.h index 06ae660..7c09e27 100644 --- a/include/app/Application.h +++ b/include/app/Application.h @@ -40,7 +40,13 @@ using std::map; using std::string; using std::vector; +/** + * @brief Type alias for a function that creates an Activity instance. + */ using CreateActivityFunc = std::function; +/** + * @brief Type alias for a function that creates a Service instance. + */ using CreateServiceFunc = std::function; class ActivityClientRecord; @@ -53,62 +59,184 @@ class ApplicationThreadStub; #define REGISTER_SERVICE(classname) \ registerService(#classname, []() -> os::app::Service* { return new classname; }); +/** + * @class Application + * @brief Represents an application that manages activities, services, and other components. + * + * This class provides an interface for lifecycle management, including creation, + * foreground, background, and destruction of the application. It also manages the + * registration and creation of activities and services, as well as handling intents. + */ class Application { public: + /** + * @brief Constructor for the Application class. + */ Application(); + /** + * @brief Destructor for the Application class. + */ virtual ~Application(); - + /** + * @brief Called when the application is created. + */ virtual void onCreate() = 0; + /** + * @brief Called when the application comes to the foreground. + */ virtual void onForeground() = 0; + /** + * @brief Called when the application goes to the background. + */ virtual void onBackground() = 0; + /** + * @brief Called when the application is destroyed. + */ virtual void onDestroy() = 0; + /** + * @brief Called when the application receives an intent. + * + * @param[in] intent The received Intent. + */ virtual void onReceiveIntent(const Intent& intent){}; - + /** + * @brief Get the package name of the application. + * + * @return The package name as a constant reference to a string. + */ const string& getPackageName() const; + /** + * @brief Set the package name for the application. + * + * @param[in] name The package name to set. + */ void setPackageName(const string& name); + /** + * @brief Get the UID of the application. + * + * @return The UID of the application. + */ int getUid() { return mUid; } + /** + * @brief Set the main loop for the application. + * + * @param[in] loop The event loop to set. + */ void setMainLoop(UvLoop* loop) { mMainLoop = loop; } + /** + * @brief Get the main loop of the application. + * + * @return The event loop associated with the application. + */ UvLoop* getMainLoop() const { return mMainLoop; } + /** + * @brief Check if the application is the system UI. + * + * @return True if the application is the system UI, false otherwise. + */ bool isSystemUI() const; - + /** + * @brief Register an activity with the application. + * + * @param[in] name The name of the activity class to register. + * @param[in] createFunc The function used to create the activity. @see CreateActivityFunc + */ void registerActivity(const string& name, const CreateActivityFunc& createFunc); + /** + * @brief Register a service with the application. + * + * @param[in] name The name of the service class to register. + * @param[in] createFunc The function used to create the service. @see CreateServiceFunc + */ void registerService(const string& name, const CreateServiceFunc& createFunc); - + /** + * @brief Get the window manager associated with the application. + * + * @return A pointer to the window manager. + */ ::os::wm::WindowManager* getWindowManager(); private: friend class ApplicationThread; friend class ApplicationThreadStub; + /** + * @brief Create an activity based on the provided name. + * + * @param[in] name The name of the activity to create. + * @return A shared pointer to the created activity. + */ std::shared_ptr createActivity(const string& name); + /** + * @brief Create a service based on the provided name. + * + * @param[in] name The name of the service to create. + * @return A shared pointer to the created service. + */ std::shared_ptr createService(const string& name); - + /** + * @brief Add an activity to the list of existing activities. + * + * @param[in] token The token of the activity. + * @param[in] activity The activity client record to add. + */ void addActivity(const sp& token, const std::shared_ptr& activity); + /** + * @brief Find an activity by its token. + * + * @param[in] token The token of the activity to find. + * @return A shared pointer to the activity client record, or nullptr if not found. + */ std::shared_ptr findActivity(const sp& token); + /** + * @brief Delete an activity by its token. + * + * @param[in] token The token of the activity to delete. + */ void deleteActivity(const sp& token); - + /** + * @brief Add a service to the list of existing services. + * + * @param[in] service The service client record to add. + */ void addService(const std::shared_ptr& service); + /** + * @brief Find a service by its token. + * + * @param[in] token The token of the service to find. + * @return A shared pointer to the service client record, or nullptr if not found. + */ std::shared_ptr findService(const sp& token); + /** + * @brief Delete a service by its token. + * + * @param token The token of the service to delete. + */ void deleteService(const sp& token); - + /** + * @brief Clear all activities and services from the application. + */ void clearActivityAndService(); private: - map, std::shared_ptr> mExistActivities; - vector> mExistServices; - string mPackageName; - map mActivityMap; - map mServiceMap; - int mUid; - int mPid; - UvLoop* mMainLoop; - ::os::wm::WindowManager* mWindowManager; + map, std::shared_ptr> + mExistActivities; /**< Map of existing activities by token. */ + vector> mExistServices; /**< List of existing services. */ + string mPackageName; /**< The package name of the application. */ + map + mActivityMap; /**< Map of activity names to their creation functions. */ + map + mServiceMap; /**< Map of service names to their creation functions. */ + int mUid; /**< The UID of the application. */ + int mPid; /**< The PID of the application. */ + UvLoop* mMainLoop; /**< The main event loop of the application. */ + ::os::wm::WindowManager* mWindowManager; /**< Window manager for the application. */ }; } // namespace app diff --git a/include/app/ApplicationThread.h b/include/app/ApplicationThread.h index dc7f422..c504464 100644 --- a/include/app/ApplicationThread.h +++ b/include/app/ApplicationThread.h @@ -26,19 +26,52 @@ namespace os { namespace app { +/** + * @brief A type alias for a function callback that takes a `void*` parameter. + */ using TASK_CALLBACK = std::function; class ApplicationThreadStub; +/** + * @class ApplicationThread + * @brief Represents a thread responsible for running the application's event loop. + * + * The `ApplicationThread` class extends `UvLoop` and is responsible for executing + * the main event loop of the application. It interacts with the `Application` class + * and provides a mechanism for managing application tasks in a separate thread. + */ class ApplicationThread : public UvLoop { public: + /** + * @brief Constructor for the ApplicationThread class. + * + * @param[in] app The application associated with this thread. + */ ApplicationThread(Application* app); + /** + * @brief Destructor for the ApplicationThread class. + */ ~ApplicationThread(); + /** + * @brief Runs the main loop for the ApplicationThread. + * + * This function is responsible for starting the event loop and processing tasks. + * + * @param[in] argc The number of command line arguments. + * @param[in] argv The array of command line arguments. + * @return An integer status code indicating the result of the main loop execution. + */ int mainRun(int argc, char** argv); + /** + * @brief Stop the application thread. + * + * Stops the event loop and halts the execution of the thread. + */ void stop(); private: - Application* mApp; + Application* mApp; /**< A pointer to the Application instance managed by this thread. */ }; } // namespace app diff --git a/include/app/BroadcastReceiver.h b/include/app/BroadcastReceiver.h index b2fd729..b7a97ec 100644 --- a/include/app/BroadcastReceiver.h +++ b/include/app/BroadcastReceiver.h @@ -21,11 +21,26 @@ namespace app { using android::binder::Status; +/** + * @class BroadcastReceiver + * @brief Abstract class for handling broadcast intents. + */ class BroadcastReceiver : public BnBroadcastReceiver { public: + /** + * @brief Called when a broadcast message is received. + * + * @param[in] intent The broadcast Intent received. + */ virtual void onReceive(const Intent& intent) = 0; private: + /** + * @brief Receives the broadcast and forwards it to `onReceive`. + * + * @param[in] intent The broadcast Intent received. + * @return The status of the broadcast reception (always returns Status::ok()). + */ Status receiveBroadcast(const Intent& intent) override { onReceive(intent); return Status::ok(); diff --git a/include/app/Context.h b/include/app/Context.h index b85e75e..0d490d4 100644 --- a/include/app/Context.h +++ b/include/app/Context.h @@ -33,78 +33,350 @@ namespace app { class Application; +/** + * @class Context + * @brief Interface providing methods to interact with the application's context. + */ class Context { public: + /** + * @brief Default constructor for Context. + */ Context() = default; + /** + * @brief Default destructor for Context. + */ virtual ~Context() = default; - + /** + * @brief Get the application associated with this context. + * + * @return A pointer to the Application instance. + */ virtual const Application* getApplication() const = 0; + /** + * @brief Get the package name associated with this context. + * + * @return A reference to the package name as a string. + */ virtual const string& getPackageName() const = 0; + /** + * @brief Get the component name associated with this context. + * + * @return A reference to the component name as a string. + */ virtual const string& getComponentName() const = 0; + /** + * @brief Get the main event loop for the application. + * + * @return A pointer to the UvLoop instance representing the main event loop. + */ virtual UvLoop* getMainLoop() const = 0; + /** + * @brief Get the current event loop for the application. + * + * @return A pointer to the UvLoop instance representing the current event loop. + */ virtual UvLoop* getCurrentLoop() const = 0; + /** + * @brief Get the token associated with this context. + * + * @return A reference to the IBinder token. + */ virtual const sp& getToken() const = 0; + /** + * @brief Get the Activity Manager for managing activities in the context. + * + * @return A reference to the ActivityManager instance. + */ virtual ActivityManager& getActivityManager() = 0; + /** + * @brief Get the Window Manager for managing window operations in the context. + * + * @return A pointer to the WindowManager instance. + */ virtual ::os::wm::WindowManager* getWindowManager() = 0; - + /** + * @brief Stop the application associated with this context. + * + * @return A status code indicating the result of stopping the application. + */ virtual int32_t stopApplication() = 0; + /** + * @brief Start an activity associated with this context. + * + * @param[in] intent The intent describing the activity to start. + * @return A status code indicating the result of starting the activity. + */ virtual int32_t startActivity(const Intent& intent) = 0; + /** + * @brief Start an activity for result with the specified intent. + * + * @param[in] intent The intent describing the activity to start. + * @param[in] requestCode The request code for identifying the result. + * @return A status code indicating the result of starting the activity. + */ virtual int32_t startActivityForResult(const Intent& intent, int32_t requestCode) = 0; + /** + * @brief Stop the activity associated with this context. + * + * @param[in] intent The intent describing the activity to stop. + * @return A status code indicating the result of stopping the activity. + */ virtual int32_t stopActivity(const Intent& intent) = 0; - + /** + * @brief Start a service associated with this context. + * + * @param[in] intent The intent describing the service to start. + * @return A status code indicating the result of starting the service. + */ virtual int32_t startService(const Intent& intent) = 0; + /** + * @brief Stop a service associated with this context. + * + * @param[in] intent The intent describing the service to stop. + * @return A status code indicating the result of stopping the service. + */ virtual int32_t stopService(const Intent& intent) = 0; + /** + * @brief Stop the currently running service in this context. + * + * @return A status code indicating the result of stopping the service. + */ virtual int32_t stopService() = 0; + /** + * @brief Bind a service to this context. + * + * @param[in] intent The intent describing the service to bind. + * @param[in] conn The connection callback for the service binding. + * @return A status code indicating the result of binding the service. + */ virtual int bindService(const Intent& intent, const sp& conn) = 0; + /** + * @brief Unbind a previously bound service in this context. + * + * @param[in] conn The connection callback for unbinding the service. + */ virtual void unbindService(const sp& conn) = 0; - + /** + * @brief Post an intent to the current context. + * + * @param[in] intent The intent to post. + * @return A status code indicating the result of posting the intent. + */ virtual int32_t postIntent(const Intent& intent) = 0; + /** + * @brief Send a broadcast with the specified intent. + * + * @param[in] intent The broadcast intent to send. + * @return A status code indicating the result of sending the broadcast. + */ virtual int32_t sendBroadcast(const Intent& intent) = 0; + /** + * @brief Register a broadcast receiver for the specified action. + * + * @param[in] action The action to register for. + * @param[in] receiver The broadcast receiver to register. + * @return A status code indicating the result of registering the receiver. + */ virtual int32_t registerReceiver(const std::string& action, const sp& receiver) = 0; + /** + * @brief Unregister a previously registered broadcast receiver. + * + * @param[in] receiver The broadcast receiver to unregister. + */ virtual void unregisterReceiver(const sp& receiver) = 0; - + /** + * @brief Set the intent for the context. + * + * @param[in] intent The intent to set. + */ virtual void setIntent(const Intent& intent) = 0; + /** + * @brief Get the current intent for the context. + * + * @return A reference to the current intent. + */ virtual const Intent& getIntent() = 0; }; +/** + * @class ContextWrapper + * @brief ContextWrapper is a wrapper around the Context class, providing additional functionality. + * + * This class allows attaching a base context, which can be used for various operations like + * managing activities, services, broadcasts, and accessing application resources. It provides + * implementations for all methods of the Context class, delegating to the base context when + * necessary. + */ class ContextWrapper : public Context { public: + /** + * @brief Get the base context wrapped by this ContextWrapper. + * + * @return A shared pointer to the base Context. + */ std::shared_ptr getContext(); + /** + * @brief Attach a base context to this ContextWrapper. + * + * @param[in] base The base context to attach. + */ void attachBaseContext(const std::shared_ptr& base); - + /** + * @brief Get the application associated with this context. + * + * @return A pointer to the Application instance. + */ const Application* getApplication() const; + /** + * @brief Get the package name associated with this context. + * + * @return A reference to the package name as a string. + */ const string& getPackageName() const override; + /** + * @brief Get the component name associated with this context. + * + * @return A reference to the component name as a string. + */ const string& getComponentName() const override; - + /** + * @brief Get the main event loop for the application. + * + * @return A pointer to the UvLoop instance representing the main event loop. + */ UvLoop* getMainLoop() const; + /** + * @brief Get the current event loop for the application. + * + * @return A pointer to the UvLoop instance representing the current event loop. + */ UvLoop* getCurrentLoop() const; + /** + * @brief Get the token associated with this context. + * + * @return A reference to the IBinder token. + */ const sp& getToken() const; + /** + * @brief Get the Activity Manager for managing activities in the context. + * + * @return A reference to the ActivityManager instance. + */ ActivityManager& getActivityManager(); + /** + * @brief Get the Window Manager for managing window operations in the context. + * + * @return A pointer to the WindowManager instance. + */ ::os::wm::WindowManager* getWindowManager(); - + /** + * @brief Stop the application associated with this context. + * + * @return A status code indicating the result of stopping the application. + */ int32_t stopApplication() override; + /** + * @brief Start an activity associated with this context. + * + * @param[in] intent The intent describing the activity to start. + * @return A status code indicating the result of starting the activity. + */ int32_t startActivity(const Intent& intent) override; + /** + * @brief Start an activity for result with the specified intent. + * + * @param[in] intent The intent describing the activity to start. + * @param[in] requestCode The request code for identifying the result. + * @return A status code indicating the result of starting the activity. + */ int32_t startActivityForResult(const Intent& intent, int32_t requestCode) override; + /** + * @brief Stop the activity associated with this context. + * + * @param[in] intent The intent describing the activity to stop. + * @return A status code indicating the result of stopping the activity. + */ int32_t stopActivity(const Intent& intent) override; - + /** + * @brief Start a service associated with this context. + * + * @param[in] intent The intent describing the service to start. + * @return A status code indicating the result of starting the service. + */ int32_t startService(const Intent& intent) override; + /** + * @brief Stop a service associated with this context. + * + * @param[in] intent The intent describing the service to stop. + * @return A status code indicating the result of stopping the service. + */ int32_t stopService(const Intent& intent) override; + /** + * @brief Stop the currently running service in this context. + * + * @return A status code indicating the result of stopping the service. + */ int32_t stopService() override; + /** + * @brief Bind a service to this context. + * + * @param[in] intent The intent describing the service to bind. + * @param[in] conn The connection callback for the service binding. + * @return A status code indicating the result of binding the service. + */ int bindService(const Intent& intent, const sp& conn) override; + /** + * @brief Unbind a previously bound service in this context. + * + * @param[in] conn The connection callback for unbinding the service. + */ void unbindService(const sp& conn) override; - + /** + * @brief Post an intent to the current context. + * + * @param[in] intent The intent to post. + * @return A status code indicating the result of posting the intent. + */ int32_t postIntent(const Intent& intent) override; + /** + * @brief Send a broadcast with the specified intent. + * + * @param[in] intent The broadcast intent to send. + * @return A status code indicating the result of sending the broadcast. + */ int32_t sendBroadcast(const Intent& intent) override; + /** + * @brief Register a broadcast receiver for the specified action. + * + * @param[in] action The action to register for. + * @param[in] receiver The broadcast receiver to register. + * @return A status code indicating the result of registering the receiver. + */ int32_t registerReceiver(const std::string& action, const sp& receiver) override; + /** + * @brief Unregister a previously registered broadcast receiver. + * + * @param[in] receiver The broadcast receiver to unregister. + */ void unregisterReceiver(const sp& receiver) override; - + /** + * @brief Set the intent for the context. + * + * @param[in] intent The intent to set. + */ void setIntent(const Intent& intent); + /** + * @brief Get the current intent for the context. + * + * @return A reference to the current intent. + */ const Intent& getIntent(); protected: - std::shared_ptr mBase; + std::shared_ptr mBase; /**< The base context wrapped by this ContextWrapper. */ }; } // namespace app diff --git a/include/app/ContextImpl.h b/include/app/ContextImpl.h index cf92929..aa18602 100644 --- a/include/app/ContextImpl.h +++ b/include/app/ContextImpl.h @@ -25,58 +25,223 @@ namespace os { namespace app { +/** + * @brief ContextImpl class that implements the Context interface. + */ class ContextImpl : public Context { public: + /** + * @brief Constructor for the ContextImpl class. + * + * @param[in] app The application associated with this context. + * @param[in] componentName The component name (e.g., Activity or Service). + * @param[in] token The IBinder token associated with this context. + * @param[in] loop The event loop associated with this context. + */ ContextImpl(const Application* app, const string& componentName, const sp& token, UvLoop* loop); - + /** + * @brief Get the application associated with this context. + * + * @return A pointer to the Application instance. + */ const Application* getApplication() const override; + /** + * @brief Get the package name associated with this context. + * + * @return A reference to the package name as a string. + */ const string& getPackageName() const override; + /** + * @brief Get the component name associated with this context. + * + * @return A reference to the component name as a string. + */ const string& getComponentName() const override; + /** + * @brief Get the main event loop for the application. + * + * @return A pointer to the UvLoop instance representing the main event loop. + */ UvLoop* getMainLoop() const override; + /** + * @brief Get the current event loop for the application. + * + * @return A pointer to the UvLoop instance representing the current event loop. + */ UvLoop* getCurrentLoop() const override; + /** + * @brief Get the token associated with this context. + * + * @return A reference to the IBinder token. + */ const sp& getToken() const override; + /** + * @brief Get the Activity Manager for managing activities in the context. + * + * @return A reference to the ActivityManager instance. + */ ActivityManager& getActivityManager() override; + /** + * @brief Get the Window Manager for managing window operations in the context. + * + * @return A pointer to the WindowManager instance. + */ ::os::wm::WindowManager* getWindowManager() override; - + /** + * @brief Static method to create an activity context. + * + * This method creates a ContextImpl for an activity context. + * + * @param[in] app The application associated with the context. + * @param[in] componentName The component name for the activity. + * @param[in] token The IBinder token associated with the activity. + * @param[in] loop The event loop for the activity. + * @return A shared pointer to a ContextImpl instance for an activity. + */ static std::shared_ptr createActivityContext(const Application* app, const string& componentName, const sp& token, UvLoop* loop); + /** + * @brief Static method to create a service context. + * + * This method creates a ContextImpl for a service context. + * + * @param[in] app The application associated with the context. + * @param[in] componentName The component name for the service. + * @param[in] token The IBinder token associated with the service. + * @param[in] loop The event loop for the service. + * @return A shared pointer to a ContextImpl instance for a service. + */ static std::shared_ptr createServiceContext(const Application* app, const string& componentName, const sp& token, UvLoop* loop); + /** + * @brief Static method to create a dialog context. + * + * This method creates a ContextImpl for a dialog context. + * + * @param[in] app The application associated with the context. + * @param[in] componentName The component name for the dialog. + * @param[in] token The IBinder token associated with the dialog. + * @param[in] loop The event loop for the dialog. + * @return A shared pointer to a ContextImpl instance for a dialog. + */ static std::shared_ptr createDialogContext(const Application* app, const string& componentName, const sp& token, UvLoop* loop); - + /** + * @brief Start an activity associated with this context. + * + * @param[in] intent The intent describing the activity to start. + * @return A status code indicating the result of starting the activity. + */ int32_t startActivity(const Intent& intent) override; + /** + * @brief Start an activity for result with the specified intent. + * + * @param[in] intent The intent describing the activity to start. + * @param[in] requestCode The request code for identifying the result. + * @return A status code indicating the result of starting the activity. + */ int32_t startActivityForResult(const Intent& intent, int32_t requestCode) override; + /** + * @brief Stop the activity associated with this context. + * + * @param[in] intent The intent describing the activity to stop. + * @return A status code indicating the result of stopping the activity. + */ int32_t stopActivity(const Intent& intent) override; + /** + * @brief Stop the application associated with this context. + * + * @return A status code indicating the result of stopping the application. + */ int32_t stopApplication() override; - + /** + * @brief Start a service associated with this context. + * + * @param[in] intent The intent describing the service to start. + * @return A status code indicating the result of starting the service. + */ int32_t startService(const Intent& intent) override; + /** + * @brief Stop a service associated with this context. + * + * @param[in] intent The intent describing the service to stop. + * @return A status code indicating the result of stopping the service. + */ int32_t stopService(const Intent& intent) override; + /** + * @brief Stop the currently running service in this context. + * + * @return A status code indicating the result of stopping the service. + */ int32_t stopService() override; + /** + * @brief Bind a service to this context. + * + * @param[in] intent The intent describing the service to bind. + * @param[in] conn The connection callback for the service binding. + * @return A status code indicating the result of binding the service. + */ int bindService(const Intent& intent, const sp& conn) override; + /** + * @brief Unbind a previously bound service in this context. + * + * @param[in] conn The connection callback for unbinding the service. + */ void unbindService(const sp& conn) override; - + /** + * @brief Post an intent to the current context. + * + * @param[in] intent The intent to post. + * @return A status code indicating the result of posting the intent. + */ int32_t postIntent(const Intent& intent) override; + /** + * @brief Send a broadcast with the specified intent. + * + * @param[in] intent The broadcast intent to send. + * @return A status code indicating the result of sending the broadcast. + */ int32_t sendBroadcast(const Intent& intent) override; + /** + * @brief Register a broadcast receiver for the specified action. + * + * @param[in] action The action to register for. + * @param[in] receiver The broadcast receiver to register. + * @return A status code indicating the result of registering the receiver. + */ int32_t registerReceiver(const std::string& action, const sp& receiver) override; + /** + * @brief Unregister a previously registered broadcast receiver. + * + * @param[in] receiver The broadcast receiver to unregister. + */ void unregisterReceiver(const sp& receiver) override; - + /** + * @brief Set the intent for the context. + * + * @param[in] intent The intent to set. + */ void setIntent(const Intent& intent) override; + /** + * @brief Get the current intent for the context. + * + * @return A reference to the current intent. + */ const Intent& getIntent() override; public: - const Application* mApp; - const string mComponentName; - const sp mToken; - UvLoop* mLoop; + const Application* mApp; /**< The application associated with this context. */ + const string mComponentName; /**< The component name (e.g., activity or service). */ + const sp mToken; /**< The binder token associated with this context. */ + UvLoop* mLoop; /**< The event loop associated with this context. */ - ActivityManager mAm; - Intent mIntent; + ActivityManager mAm; /**< The Activity Manager for managing activities. */ + Intent mIntent; /**< The intent associated with this context. */ }; } // namespace app diff --git a/include/app/Dialog.h b/include/app/Dialog.h index 9f93e9c..13cdb09 100644 --- a/include/app/Dialog.h +++ b/include/app/Dialog.h @@ -28,21 +28,72 @@ class LayoutParams; namespace app { +/** + * @class Dialog + * @brief Represents a dialog window in the application context. + */ class Dialog : public ContextWrapper { public: + /** + * @brief Constructor for the Dialog class. + * + * @param[in] context A shared pointer to the Context associated with this Dialog. + */ Dialog(const std::shared_ptr& context); + /** + * @brief Destructor for the Dialog class. + */ ~Dialog(); + /** + * @brief Static method to create a Dialog instance. + * + * @param context The context in which the dialog will be created. + * @return A shared pointer to the created Dialog instance. + */ static std::shared_ptr createDialog(Context* context); - + /** + * @brief Set the layout parameters for the dialog. + * + * This method allows setting the layout parameters for the dialog's window. The layout + * parameters include things like width, height, gravity, etc. + * + * @param layout A reference to a LayoutParams object containing the desired layout parameters. + */ void setLayout(wm::LayoutParams& layout); + /** + * @brief Get the current layout parameters of the dialog. + * + * @return A LayoutParams object containing the current layout parameters of the dialog. + */ wm::LayoutParams getLayout(); + /** + * @brief Get the root view of the dialog. + */ void* getRoot(); + /** + * @brief Show the dialog. + */ void show(); + /** + * @brief Hide the dialog. + */ void hide(); + /** + * @brief Set the position and size of the dialog. + * + * This method sets the position (left and top) and size (width and height) of the dialog + * window. + * + * @param[in] left The left position of the dialog window. + * @param[in] top The top position of the dialog window. + * @param[in] width The width of the dialog window. + * @param[in] height The height of the dialog window. + */ void setRect(int32_t left, int32_t top, int32_t width, int32_t height); private: - std::shared_ptr<::os::wm::BaseWindow> mDialog; + std::shared_ptr<::os::wm::BaseWindow> + mDialog; /**< A shared pointer to the BaseWindow instance representing the dialog. */ }; } // namespace app diff --git a/include/app/Intent.h b/include/app/Intent.h index 8799da0..7c74b2e 100644 --- a/include/app/Intent.h +++ b/include/app/Intent.h @@ -25,57 +25,131 @@ namespace os { namespace app { +/** + * @class Intent + * @brief Represents an intent used for application communication and activity management. + * + * The `Intent` class is used to describe an action to be performed, the target of the action, + * the data to be processed, and any flags or extra information related to the intent. + */ class Intent : public android::Parcelable { public: - std::string mTarget; - std::string mAction; - std::string mData; - uint32_t mFlag; + std::string mTarget; /**< The target of the intent (e.g., an activity or service). */ + std::string mAction; /**< The action to be performed (e.g., ACTION_VIEW). */ + std::string mData; /**< Data associated with the intent (e.g., a URI). */ + uint32_t mFlag; /**< Flags that modify the behavior of the intent (e.g., + FLAG_ACTIVITY_NEW_TASK). */ /** PersistableBundle,a mapping from String values to various types */ - android::os::PersistableBundle mExtra; + android::os::PersistableBundle mExtra; /**< Extra data as a key-value mapping. */ + /** + * @enum Flag Constants + * @brief Intent flags used to define special behavior for the activity or task. + */ enum { - NO_FLAG = 0, - FLAG_ACTIVITY_NEW_TASK = 1, - FLAG_ACTIVITY_SINGLE_TOP = 2, - FLAG_ACTIVITY_CLEAR_TOP = 4, - FLAG_ACTIVITY_CLEAR_TASK = 8, + NO_FLAG = 0, /**< No flags set. */ + FLAG_ACTIVITY_NEW_TASK = 1, /**< Start a new task for the activity. */ + FLAG_ACTIVITY_SINGLE_TOP = 2, /**< If the activity is already at the top, its onNewIntent() + method is called, otherwise a new instance is created. */ + FLAG_ACTIVITY_CLEAR_TOP = + 4, /**< If an instance of activity already exists in the task, its onNewIntent() + method is called, and clear activities above the current one. */ + FLAG_ACTIVITY_CLEAR_TASK = + 8, /**< Clear the task stack and start a new instance of the activity. */ - FLAG_APP_SWITCH_TASK = 1024, // only switch task, don't set new intent - FLAG_APP_MOVE_BACK, // move app to background,it only works in stopActivity + FLAG_APP_SWITCH_TASK = 1024, /** only switch task, don't set new intent */ + FLAG_APP_MOVE_BACK, /**< move app to background, it only works in stopActivity */ }; - + /** + * @brief Constructor for the Intent class. + * + * Initializes the intent with default values. + */ Intent() : mFlag(NO_FLAG){}; + /** + * @brief Default destructor for the Intent class. + */ ~Intent() = default; + /** + * @brief Constructor that initializes the target of the intent. + * + * @param[in] target The target of the intent (e.g., activity or service). + */ Intent(const std::string& target) : mTarget(target), mFlag(NO_FLAG) {} + /** + * @brief Sets the target of the intent. + * + * @param[in] target The target of the intent (e.g., activity or service). + */ void setTarget(const std::string& target); + /** + * @brief Sets the action of the intent. + * + * @param[in] action The action to be performed. + */ void setAction(const std::string& action); + /** + * @brief Sets the data associated with the intent. + * + * @param[in] data The data to be performed, typically in URI format. + */ void setData(const std::string& data); + /** + * @brief Sets the flags of the intent. + * + * @param[in] flag The flags to be set for the intent. + */ void setFlag(const int32_t flag); + /** + * @brief Sets additional data for the intent as a `PersistableBundle`. + * + * @param[in] extra The additional data to be included in the intent. + */ void setBundle(const android::os::PersistableBundle& extra); - + /** + * @brief Reads the intent data from a parcel. + * + * This function is used to deserialize the intent from a parcel. + * + * @param[in] parcel The parcel containing the serialized intent data. + * @return android::OK on success and an appropriate error otherwise. + */ android::status_t readFromParcel(const android::Parcel* parcel) final; + /** + * @brief Writes the intent to a parcel. + * + * @param[in] parcel The parcel to which the intent will be written. + * @return Returns android::OK on success and an appropriate error otherwise. + */ android::status_t writeToParcel(android::Parcel* parcel) const final; public: /****************** target definition *****************/ - static const std::string TARGET_PREFLEX; - static const std::string TARGET_ACTIVITY_TOPRESUME; - static const std::string TARGET_APPLICATION_FOREGROUND; - static const std::string TARGET_APPLICATION_HOME; + static const std::string TARGET_PREFLEX; /**< Target for the prefixed application. */ + static const std::string + TARGET_ACTIVITY_TOPRESUME; /**< Target for the top activity to resume. */ + static const std::string + TARGET_APPLICATION_FOREGROUND; /**< Target for bringing the app to foreground. */ + static const std::string TARGET_APPLICATION_HOME; /**< Target for the home screen. */ /******************************************************/ /****************** action definition *****************/ - static const std::string ACTION_BOOT_READY; - static const std::string ACTION_BOOT_COMPLETED; - static const std::string ACTION_HOME; - static const std::string ACTION_BOOT_GUIDE; - static const std::string ACTION_BACK_PRESSED; + static const std::string + ACTION_BOOT_READY; /**< Action that signals the system is ready to boot.*/ + static const std::string + ACTION_BOOT_COMPLETED; /**< Action that signals the system has completed booting. */ + static const std::string ACTION_HOME; /**< Action that corresponds to the home button press. */ + static const std::string + ACTION_BOOT_GUIDE; /**< Action that corresponds to the boot guide (initial setup). */ + static const std::string + ACTION_BACK_PRESSED; /**< Action that corresponds to the back button press. */ // broadcast - static const std::string BROADCAST_APP_START; - static const std::string BROADCAST_APP_EXIT; - static const std::string BROADCAST_TOP_ACTIVITY; + static const std::string + BROADCAST_APP_START; /**< Broadcast action signaling that an app has started. */ + static const std::string + BROADCAST_APP_EXIT; /**< Broadcast action signaling that an app has exited. */ + static const std::string BROADCAST_TOP_ACTIVITY; /**< Broadcast action for the top activity. */ /******************************************************/ }; // class Intent diff --git a/include/app/MessageService.h b/include/app/MessageService.h index 24c1357..b894ff6 100644 --- a/include/app/MessageService.h +++ b/include/app/MessageService.h @@ -31,9 +31,25 @@ using android::sp; using android::binder::Status; using os::app::IReply; +/** + * @class ReplySender + * @brief A class that sends replies to a message receiver. + */ class ReplySender { public: + /** + * @brief Constructor that initializes the ReplySender with a sequence number and reply + * interface. + * + * @param[in] seqNo The sequence number of the message. + * @param[in] reply The interface through which the reply will be sent. + */ ReplySender(const int seqNo, const sp& reply) : mSeqNo(seqNo), mReply(reply) {} + /** + * @brief Sends the reply to the receiver. + * + * @param[in] reply The reply message to be sent. + */ void reply(const std::string& reply) { Status status = mReply->onReply(mSeqNo, reply); if (!status.isOk()) { @@ -42,25 +58,58 @@ class ReplySender { } private: - const int mSeqNo; - const sp mReply; + const int mSeqNo; /**< The sequence number for the reply message */ + const sp mReply; /**< The interface used to send the reply. */ }; +/** + * @class ReplyReceiver + * @brief A class to receive replies for messages. + */ class ReplyReceiver : public BnReply { public: + /** + * @brief Abstract method to handle the received reply. + * + * @param[in] seqNo The sequence number of the reply. + * @param[in] data The reply data received. + */ virtual void receiveReply(int seqNo, const std::string& data) = 0; private: + /** + * @brief Internal method that is invoked to deliver the reply to the receiver. + * + * @param[in] seqNo The sequence number of the reply. + * @param[in] reply The reply data. + * @return Returns Status::ok() to indicate success. + */ Status onReply(int32_t seqNo, const ::std::string& reply) override { receiveReply(seqNo, reply); return Status::ok(); } }; +/** + * @class MessageChannel + * @brief A class to send and receive messages through a message channel. + */ class MessageChannel { public: + /** + * @brief Constructor that initializes the MessageChannel with the service. + * + * @param[in] service The `IMessageChannel` service through which messages will be sent. + */ MessageChannel(const sp& service) : mService(service) {} - + /** + * @brief Sends a message and receives a reply synchronously. + * + * This method sends a message to the service and waits for a reply. + * + * @param[in] request The request message to send. + * @return The reply message received from the service. + */ std::string sendMessageAndReply(const string& request) { std::string ret; Status status = mService->sendMessageAndReply(request, &ret); @@ -69,7 +118,13 @@ class MessageChannel { } return ret; } - + /** + * @brief Sends a message with a sequence number and a reply handler. + * + * @param[in] request The request message to send. + * @param[in] seqNo The sequence number of the message. + * @param[in] reply The reply handler to process the received reply. + */ void sendMessage(const std::string& request, const int seqNo, const sp reply) { Status status = mService->sendMessage(request, seqNo, reply); if (!status.isOk()) { @@ -78,24 +133,63 @@ class MessageChannel { } private: - sp mService; + sp mService; /**< The service used to send and receive messages. */ }; +/** + * @class MessageServiceInterface + * @brief Interface for message services. + */ class MessageServiceInterface { public: + /** + * @brief Receives a message and sends a reply synchronously. + * + * @param[in] request The request message to receive. + * @return The reply message to be sent back. + */ virtual std::string receiveMessageAndReply(const string& request) = 0; + /** + * @brief Receives a message and handles the reply asynchronously. + * + * @param[in] request The request message to receive. + * @param[in] reply A shared pointer to the `ReplySender` object to send a reply. + */ virtual void receiveMessage(const std::string& request, const std::shared_ptr& reply) = 0; }; +/** + * @class BnMessageService + * @brief Implementation of the MessageService interface. + */ class BnMessageService : public BnMessageChannel { public: + /** + * @brief Constructor that initializes the BnMessageService with a service instance. + * + * @param[in] service The service instance that implements the message handling logic. + */ BnMessageService(MessageServiceInterface* service) : mService(service) {} + /** + * @brief Sends a message and receives a reply synchronously. + * + * @param[in] request The request message to send. + * @param[in] reply The string to store the reply message. + * @return Returns `Status::ok()` on success. + */ Status sendMessageAndReply(const std::string& request, std::string* reply) override { *reply = mService->receiveMessageAndReply(request); return Status::ok(); } - + /** + * @brief Sends a message with a sequence number and a reply handler asynchronously. + * + * @param[in] request The request message to send. + * @param[in] seqNo The sequence number of the message. + * @param[in] reply The reply handler to process the reply. + * @return Status Returns `Status::ok()` on success. + */ Status sendMessage(const std::string& request, int32_t seqNo, const sp& reply) override { auto replyHandler = std::make_shared(seqNo, reply); @@ -104,26 +198,46 @@ class BnMessageService : public BnMessageChannel { } public: - MessageServiceInterface* mService; + MessageServiceInterface* mService; /**< The service instance used to handle messages. */ }; +/** + * @class MessageService + * @brief A service that implements the MessageService interface. + */ class MessageService : public Service, public MessageServiceInterface { public: + /** + * @brief Constructor that initializes the MessageService with a binder service. + */ MessageService() { mBinderService = sp::make(this); }; - + /** + * @brief Abstract method for binding the service with an intent. + * + * @param[in] intent The intent used to bind the service. + */ virtual void onBindExt(const Intent& intent) = 0; private: - // we need to return the bindService, and notify the user of bind. + /** + * @brief Binds the service and returns the binder interface. + * + * This method is called to bind the service and notify the user. It returns + * the binder interface for the message service. + * + * @param intent The intent used for binding. + * @return The binder object associated with the service. + */ sp onBind(const Intent& intent) override { onBindExt(intent); return mBinderService; } private: - sp mBinderService; + sp + mBinderService; /**< The binder service used to communicate with the service. */ }; } // namespace app diff --git a/include/app/Service.h b/include/app/Service.h index 9ccea08..c9ad95d 100644 --- a/include/app/Service.h +++ b/include/app/Service.h @@ -28,25 +28,75 @@ using os::app::IServiceConnection; class ServiceClientRecord; +/** + * @class Service + * @brief Base class for implementing a service that runs in the background. + */ class Service : public ContextWrapper { public: + /** + * @brief Constructs a Service object. + */ Service(); + /** + * @brief Default destructor for Service. + */ virtual ~Service() = default; - + /** + * @brief Called when the service is created. + */ virtual void onCreate() = 0; + /** + * @brief Called when the service receives a start command. + * + * @param[in] intent The intent that started the service. + */ virtual void onStartCommand(const Intent& intent) = 0; + /** + * @brief Called when the service is destroyed. + */ virtual void onDestroy() = 0; + /** + * @brief Called when a client binds to the service. + * + * @param[in] intent The intent used for binding the service. + * @return A binder object that clients can use to interact with the service. + */ virtual sp onBind(const Intent& intent); + /** + * @brief Called when a client unbinds from the service. + * + * @return Returns true if unbind operation was successful, otherwise `false`. + */ virtual bool onUnbind(); + /** + * @brief Called when an intent is received by the service. + * + * @param[in] intent The intent that was received. + */ virtual void onReceiveIntent(const Intent& intent){}; private: friend class ServiceClientRecord; + /** + * @brief Binds the service to a client. + * + * This function is used internally to bind the service to a client connection. It establishes + * the communication channel between the service and the client. + * + * @param[in] intent The Intent object containing information about the bind request. + * @param[in] conn The service connection interface to communicate with the client. + * @return int A status code indicating the result of the bind operation. + */ int bind(const Intent& intent, const sp& conn); + /** + * @brief Unbinds the service from the client. + */ void unbind(); - sp mServiceBinder; - bool mIsBinded; + sp + mServiceBinder; /**< The binder object that clients use to interact with the service. */ + bool mIsBinded; /**< Flag indicating whether the service is bound to a client */ }; } // namespace app diff --git a/include/app/ServiceConnection.h b/include/app/ServiceConnection.h index 27fc265..7f279fa 100644 --- a/include/app/ServiceConnection.h +++ b/include/app/ServiceConnection.h @@ -26,16 +26,42 @@ using android::IBinder; using android::sp; using android::binder::Status; +/** + * @class ServiceConnection + * @brief A class that handles the connection and disconnection events of a service. + */ class ServiceConnection : public BnServiceConnection { public: + /** + * @brief Called when the service is successfully connected. + * + * @param[in] server The IBinder object representing the service that has been connected. + */ virtual void onConnected(const sp& server) = 0; + /** + * @brief Called when the service is disconnected. + * + * @param[in] server The IBinder object representing the service that has been disconnected. + */ virtual void onDisconnected(const sp& server) = 0; private: + /** + * @brief Internal method that is invoked when the service is connected. + * + * @param[in] server The IBinder object representing the connected service. + * @return The status of the connection (always returns Status::ok()). + */ Status onServiceConnected(const sp& server) override { onConnected(server); return Status::ok(); } + /** + * @brief Internal method that is invoked when the service is disconnected. + * + * @param[in] server The IBinder object representing the disconnected service. + * @return The status of the disconnection (always returns Status::ok()). + */ Status onServiceDisconnected(const sp& server) override { onDisconnected(server); return Status::ok(); diff --git a/include/app/UvLoop.h b/include/app/UvLoop.h index 4388e0f..4905c5a 100644 --- a/include/app/UvLoop.h +++ b/include/app/UvLoop.h @@ -26,20 +26,53 @@ namespace os { namespace app { +/** + * @brief Type alias for a callback function that takes a `void*` as an argument. + */ using UV_CALLBACK = std::function; +/** + * @brief Closes a libuv handle if it is not already in the process of closing. + * + * @param[in] handler The uv handle to be closed. + */ inline void uvCloseHandle(uv_handle_t* handler) { if (!uv_is_closing(handler)) { uv_close(handler, NULL); } } +/** + * @class UvMsgQueue + * @brief A message queue that posts messages to a UV loop asynchronously. + * + * `UvMsgQueue` is a thread-safe queue that posts messages to a UV loop for asynchronous processing. + * The queue uses an `uv_async_t` handle to notify the loop when a new message is available to + * process. + * + * @tparam T The type of messages to be handled by the queue. + */ template class UvMsgQueue { public: + /** + * @brief Default constructor for the UvMsgQueue. + */ UvMsgQueue() {} + /** + * @brief Default destructor for the UvMsgQueue. + */ virtual ~UvMsgQueue() {} - + /** + * @brief Attaches the message queue to a libuv loop. + * + * This function initializes the `uv_async_t` handle and associates it with the provided + * `uv_loop_t`. When a message is pushed into the queue, the libuv event loop will invoke the + * callback to process the message. + * + * @param loop The libuv loop to attach to. + * @return Returns `0` on success, or a non-zero value on error. + */ int attachLoop(uv_loop_t* loop) { mUvAsync.data = this; return uv_async_init(loop, &mUvAsync, [](uv_async_t* handle) { @@ -47,27 +80,53 @@ class UvMsgQueue { my->processMessage(); }); } - + /** + * @brief Pushes a message to the queue and triggers processing. + * + * This function adds a message to the queue and signals the event loop to process the message + * asynchronously. + * + * @param[in] msg The message to be pushed. + * @return Returns 0 on success, or a non-zero value on error. + */ int push(T& msg) { std::lock_guard lock(mMutex); mQueue.push(msg); return uv_async_send(&mUvAsync); } - + /** + * @brief Emplaces a message to the queue and triggers processing. + * + * This function emplaces a message into the queue (using perfect forwarding) and triggers the + * event loop to process it. + * + * @tparam[in] Args The argument types used to construct the message. + * @param[in] args Arguments to construct the message. + * @return Returns 0 on success, or a non-zero value on error. + */ template int emplace(Args&&... args) { std::lock_guard lock(mMutex); mQueue.emplace(std::forward(args)...); return uv_async_send(&mUvAsync); } - + /** + * @brief Handle messages from the queue. + * + * @param[in] msg The message to be processed. + */ virtual void handleMessage(const T& msg) = 0; - + /** + * @brief Closes the message queue and cleans up resources. + */ void close() { uvCloseHandle((uv_handle_t*)&mUvAsync); } private: + /** + * @brief Processes and handles all messages in the queue. + */ void processMessage() { std::lock_guard lock(mMutex); while (!mQueue.empty()) { @@ -77,63 +136,173 @@ class UvMsgQueue { } private: - std::mutex mMutex; - std::queue mQueue; - uv_async_t mUvAsync; + std::mutex mMutex; /**< Mutex to protect access to the queue. */ + std::queue mQueue; /**< The queue of messages to be processed. */ + uv_async_t mUvAsync; /**< The uv_async handle for triggering message processing. */ }; +/** + * @class UvLoop + * @brief Represents the event loop for the application. + */ class UvLoop { public: + /** + * @brief Constructs a UvLoop using the default loop. + * + * @param[in] useDefault Whether to use the default loop. + */ UvLoop(bool useDefault = false); - /** use exist uvloop */ + /** + * @brief Constructs a UvLoop using an existing libuv loop. + * + * @param[in] loop An existing `uv_loop_t` to use. + */ UvLoop(uv_loop_t* loop); - + /** + * @brief A callback type for tasks posted to the loop. + */ using TaskCB = std::function; + /** + * @brief A structure used for message callbacks in the event loop. + */ struct MsgCB { TaskCB callback; MsgCB(const TaskCB& cb) : callback(cb) {} }; + /** + * @class MessageHandler + * @brief A message handler class that processes task messages. + * + * This class is used internally to process tasks in the event loop. + */ class MessageHandler : public UvMsgQueue { + /** + * @brief Handle messages from the queue. + * + * @param[in] msg The message to be processed. + */ void handleMessage(const MsgCB& msg) override { msg.callback(); } }; + /** + * @brief Posts a task to the event loop for execution. + * + * This function adds a task (callback) to be executed in the event loop. + * + * @param[in] cb The callback function to be executed. + * @return Returns 0 on success, or a non-zero value on error. + */ int postTask(TaskCB&& cb) { return mMsgHandler.emplace(cb); } - + /** + * @brief Retrieves the underlying uv_loop_t handle. + * + * @return The `uv_loop_t` handle. + */ uv_loop_t* get() const; + /** + * @brief Posts a delayed task to the event loop. + * + * This function posts a task to the event loop that will be executed after a specified delay. + * + * @param[in] callback The callback function to be executed. + * @param[in] timeout The delay (in milliseconds) before the task is executed. + * @param[in] data Optional data to pass to the callback. + * @return Returns 0 on success, or a non-zero value on error. + */ int postDelayTask(const UV_CALLBACK& callback, uint64_t timeout, void* data = nullptr); - + /** + * @brief Runs the event loop. + * + * This function starts the event loop and keeps it running until the loop is stopped. + * + * @param[in] mode The run mode. + * @return Returns 0 on success, or a non-zero value on error. + */ int run(uv_run_mode mode = UV_RUN_DEFAULT); + /** + * @brief Checks if the event loop is alive (still running). + * + * @return True if the event loop is running, false otherwise. + */ bool isAlive(); + /** + * @brief Closes the event loop and frees resources. + * + * This function stops the event loop and releases any resources associated with it. + * + * @return Returns 0 on success, or a non-zero value on error. + */ int close(); + /** + * @brief Stops the event loop immediately. + * + * This function stops the event loop from running and schedules it for closing. + */ void stop(); + /** + * @brief Prints information about all active handles in the event loop. + */ void printAllHandles(); private: - // Custom deleter + /** + * @brief Custom deleter for `uv_loop_t` to manage the event loop lifecycle. + */ typedef std::function Deleter; + /** + * @brief Destroy a libuv loop. + * + * @param[in] loop The `uv_loop_t` instance to be destroyed. + */ void destroy(uv_loop_t* loop) const { if (!mIsDefaultLoop) { delete loop; } } - bool mIsDefaultLoop; - std::unique_ptr mLooper; - MessageHandler mMsgHandler; + bool mIsDefaultLoop; /**< Whether the loop is the default libuv loop. */ + std::unique_ptr mLooper; /**< The `uv_loop_t` object managed by the loop. */ + MessageHandler mMsgHandler; /**< The message handler used for processing tasks. */ }; +/** + * @class UvAsync + * @brief A class for handling asynchronous events with libuv. + * + * This class wraps the `uv_async_t` handle to provide an easy-to-use interface for posting tasks to + * the event loop. The task is processed asynchronously when triggered by `uv_async_send()`. + */ class UvAsync { public: + /** + * @brief Default constructor for the UvAsync class. + */ UvAsync() {} + /** + * @brief Constructor that initializes the async handle with a loop and a callback. + * + * @param[in] loop The `uv_loop_t` to associate with the async handle. + * @param[in] cb The callback function to be executed when the task is triggered. + */ UvAsync(uv_loop_t* loop, const UV_CALLBACK& cb) { init(loop, cb); } + /** + * @brief Destructor for the UvAsync class. + */ ~UvAsync() { close(); } - + /** + * @brief Initializes the async handle with a loop and a callback. + * + * @param[in] loop The `uv_loop_t` to associate with the async handle. + * @param[in] cb The callback function to be executed when the async handle is triggered. + * @return Returns 0 on success, or a non-zero value on error. + */ int init(uv_loop_t* loop, const UV_CALLBACK& cb) { mWillDelete = false; mCallback = cb; @@ -149,47 +318,100 @@ class UvAsync { }); } - /** send and delete self after be processed */ + /** + * @brief Sends an asynchronous message and deletes the object after processing. + * + * This function sends the message and ensures that the object is deleted after the message is + * processed. + * + * @param[in] data Optional data to be passed to the callback. + * @return Returns 0 on success, or a non-zero value on error. + */ int sendOnce(void* data = nullptr) { mWillDelete = true; return send(data); } - + /** + * @brief Sends an asynchronous message. + * + * This function sends the message to the async handle and triggers the callback when processed. + * + * @param[in] data Optional data to be passed to the callback. + * @return Returns 0 on success, or a non-zero value on error. + */ int send(void* data = nullptr) { mData = data; return uv_async_send(&mHandler); } - + /** + * @brief Closes the async handle and releases resources. + */ void close() { uvCloseHandle((uv_handle_t*)&mHandler); } private: - uv_async_t mHandler; - bool mWillDelete; - UV_CALLBACK mCallback; - void* mData; + uv_async_t mHandler; /**< The libuv async handle. */ + bool mWillDelete; /**< Whether the object should be deleted after processing. */ + UV_CALLBACK mCallback; /**< The callback to execute when the task is processed. */ + void* mData; /**< The data passed to the callback. */ }; +/** + * @class UvTimer + * @brief A class for creating and managing libuv timers. + * + * This class provides a wrapper for `uv_timer_t`, allowing you to start, stop, and restart timers + * with custom callbacks. + */ class UvTimer { public: + /** + * @brief Default constructor for the UvTimer class. + * + * This initializes the timer handle but does not associate it with a loop yet. + */ UvTimer() { mHandler = new uv_timer_t; } + /** + * @brief Constructor that initializes the timer with a loop and a callback. + * + * @param[in] loop The `uv_loop_t` to associate with the timer. + * @param[in] cb The callback function to be executed when the timer expires. + */ UvTimer(uv_loop_t* loop, const UV_CALLBACK& cb) { mHandler = new uv_timer_t; init(loop, cb); } + /** + * @brief Destructor for the UvTimer class. + * + * This ensures the timer handle is closed and cleaned up. + */ ~UvTimer() { close(); } - + /** + * @brief Initializes the timer with a loop and a callback. + * + * @param[in] loop The `uv_loop_t` to associate with the timer. + * @param[in] cb The callback function to be executed when the timer expires. + * @return Returns 0 on success, or a non-zero value on error. + */ int init(uv_loop_t* loop, const UV_CALLBACK& cb) { mCallback = cb; mHandler->data = this; return uv_timer_init(loop, mHandler); } - + /** + * @brief Starts the timer with the specified timeout and repeat interval. + * + * @param[in] timeout The initial timeout (in milliseconds). + * @param[in] repeat The repeat interval (in milliseconds, 0 for no repeat). + * @param[in] data Optional data to pass to the callback. + * @return Returns `0` on success, or a non-zero value on error. + */ int start(int64_t timeout, int64_t repeat = 0, void* data = nullptr) { mData = data; return uv_timer_start( @@ -200,15 +422,25 @@ class UvTimer { }, timeout, repeat); } - + /** + * @brief Stops the timer. + * + * @return Returns 0 on success, or a non-zero value on error. + */ int stop() { return uv_timer_stop(mHandler); } - + /** + * @brief Restarts the timer to trigger again after the specified interval. + * + * @return Returns 0 on success, or a non-zero value on error. + */ int again() { return uv_timer_again(mHandler); } - + /** + * @brief Closes the timer and releases resources. + */ void close() { if (mHandler && !uv_is_closing((uv_handle_t*)mHandler)) { uv_close((uv_handle_t*)mHandler, @@ -218,27 +450,64 @@ class UvTimer { } private: - uv_timer_t* mHandler; - UV_CALLBACK mCallback; - void* mData; + uv_timer_t* mHandler; /**< The libuv timer handle. */ + UV_CALLBACK mCallback; /**< The callback to execute when the timer expires. */ + void* mData; /**< The data passed to the callback. */ }; +/** + * @class UvPoll + * @brief A class for handling file descriptor-based events in libuv. + * + * This class wraps the `uv_poll_t` handle to allow monitoring file descriptors for events such as + * readability and writability. It can be used to monitor sockets or any other file descriptors. + */ class UvPoll { public: + /** + * @brief Default constructor for the UvPoll class. + */ UvPoll() {} + /** + * @brief Constructor that initializes the poll handle with a loop and a file descriptor. + * + * @param[in] loop The `uv_loop_t` to associate with the poll handle. + * @param[in] fd The file descriptor to monitor. + */ UvPoll(uv_loop_t* loop, int fd) { init(loop, fd); } + /** + * @brief Destructor for the UvPoll class. + * + * This ensures the poll handle is closed and cleaned up. + */ ~UvPoll() { close(); } - + /** + * @brief Initializes the poll handle with a loop and a file descriptor. + * + * @param[in] loop The `uv_loop_t` to associate with the poll handle. + * @param[in] fd The file descriptor to monitor. + * @return Returns 0 on success, or a non-zero value on error. + */ int init(uv_loop_t* loop, int fd) { mHandler.data = this; return uv_poll_init(loop, &mHandler, fd); } - + /** + * @brief A callback type for handling poll events. + */ using PollCallBack = std::function; + /** + * @brief Starts polling the file descriptor for events. + * + * @param[in] event The events to monitor (e.g., read, write). + * @param[in] cb The callback function to be executed when the events occur. + * @param[in] data Optional data to be passed to the callback function. + * @return Returns 0 on success, or a non-zero value on error. + */ int start(int event, const PollCallBack& cb, void* data = nullptr) { mCallback = cb; mData = data; @@ -247,19 +516,25 @@ class UvPoll { my->mCallback(handle->io_watcher.fd, status, events, my->mData); }); } - + /** + * @brief Stops monitoring the file descriptor. + * + * @return Returns 0 on success, or a non-zero value on error. + */ int stop() { return uv_poll_stop(&mHandler); } - + /** + * @brief Closes the poll handle and releases resources. + */ void close() { uvCloseHandle((uv_handle_t*)&mHandler); } private: - uv_poll_t mHandler; - PollCallBack mCallback; - void* mData; + uv_poll_t mHandler; /**< The libuv poll handle */ + PollCallBack mCallback; /**< The callback to invoke when an event occurs */ + void* mData; /**< Optional data to pass to the callback */ }; } // namespace app