Add descriptions to service_loader.h file

Signed-off-by: Hwankyu Jhun <h.jhun@samsung.com>

diff --git a/include/service_loader.h b/include/service_loader.h
index 44658088df7f7e7c2eaf56b36f54dc52bb4e5823..69551ea684073f61709c6b04ad5dcafc9a28331d 100644 (file)
--- a/include/service_loader.h
+++ b/include/service_loader.h
@@ -24,33 +24,202 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Enumeration for the service loader result.
+ * @since_tizen 10.0
+ */
 typedef enum {
-  SERVICE_LOADER_ERROR_NONE = TIZEN_ERROR_NONE,
-  SERVICE_LOADER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,
-  SERVICE_LOADER_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,
-  SERVICE_LOADER_ERROR_INVALID_CONTEXT = TIZEN_ERROR_APPLICATION | 0x01,
-  SERVICE_LOADER_ERROR_ALREADY_RUNNING = TIZEN_ERROR_FILE_EXISTS,
+  SERVICE_LOADER_ERROR_NONE = TIZEN_ERROR_NONE,  /**< Successful */
+  SERVICE_LOADER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,  /**< Invalid parameter */
+  SERVICE_LOADER_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,  /**< Out of memory */
+  SERVICE_LOADER_ERROR_INVALID_CONTEXT = TIZEN_ERROR_APPLICATION | 0x01,  /**< Invalid context */
+  SERVICE_LOADER_ERROR_ALREADY_RUNNING = TIZEN_ERROR_FILE_EXISTS,  /**< Service loader is already running */
 } service_error_e;
 
+/**
+ * @brief Called when the service loader starts.
+ * @details The callback function is called before the main loop of the service loader starts.
+ *          In this callback, you can initialize service resources like data structures or files.
+ * @since_tizen 10.0
+ * @param[in] user_data The user data passed from the registration function
+ * @pre service_loader_run() will invoke this callback function.
+ * @see service_loader_run()
+ * @see #service_loader_lifecycle_callback_s
+ */
 typedef void (*service_loader_create_cb)(void *user_data);
 
+/**
+ * @brief Called when the main loop of the service loader exits.
+ * @details You should release resources of the service loader in this function.
+ * @since_tizen 10.0
+ * @param[in] user_data The use data passed from the registeration function
+ * @see service_loader_run()
+ * @see #service_loader_lifecycle_callback_s
+ */
 typedef void (*service_loader_destroy_cb)(void *user_data);
 
+/**
+ * @brief Called when the service loader receives the message.
+ * @since_tizen 10.0
+ * @param[in] sender The name of the sender
+ * @param[in] envelope The message
+ * @param[in] user_data The user data passed from the registration function
+ * @see service_loader_run()
+ * @see #service_loader_lifecycle_callback_s
+ */
 typedef void (*service_loader_message_cb)(const char *sender, bundle *envelope,
                                           void *user_data);
 
+/**
+ * @brief The structure type containing the set of callback functions for handling service loader lifecycle events.
+ * @details It's one of the input parameters of the service_loader_run() function.
+ * @since_tizen 10.0
+ * @see service_loader_run()
+ * @see service_loader_create_cb()
+ * @see service_loader_destroy_cb()
+ * @see service_loader_message_cb()
+ */
 typedef struct {
-  service_loader_create_cb create;
-  service_loader_destroy_cb destroy;
-  service_loader_message_cb message;
+  service_loader_create_cb create;  /**< This callback is called at the start of the service loader. */
+  service_loader_destroy_cb destroy;  /**< This callback function is called once after the main loop of the service loader exits. */
+  service_loader_message_cb message;  /**< This callback function is called when the message is delivered. */
 } service_loader_lifecycle_callback_s;
 
+/**
+ * @brief Runs the main loopf of the service loader until service_loader_quit() is called.
+ * @details This function is main entry point of the service loader.
+ *          The service_loader_create_cb() callback function is called to initialize the service loader before the main loop of the service loader start up.
+ *          This main loop supports event handling for the GMainLoop.
+ * @since_tizen 10.0
+ * @param[in] argc The argument count
+ * @param[in] argv The argument vector
+ * @param[in] name The name of the service loader
+ * @param[in] callback The set of callback functions to handle service loader lifecycle events
+ * @param[in] user_data The user data to be passed to the callback functions
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #SERVICE_LOADER_ERROR_NONE Successful
+ * @retval #SERVICE_LOADER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SERVICE_LOADER_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #SERVICE_LOADER_ERROR_ALREADY_RUNNING The service loader is already running
+ * @see service_loader_create_cb()
+ * @see service_loader_destroy_cb()
+ * @see service_loader_message_cb()
+ * @see service_loader_quit()
+ * @see #service_loader_lifecycle_callback_s
+ * 
+ * @code
+#include <service_loader.h>
+
+static void LoaderCreateCb(void* user_data) {
+  // ...
+}
+
+static void LoaderDestroyCb(void* user_data) {
+  // ...
+}
+
+static void LoaderMessageCb(const char* sender, bundle* envelope, void* user_data) {
+  // ...
+}
+
+int main(int argc, char** argv) {
+  service_loader_lifecycle_callback_s callback = {
+    .create = LoaderCreateCb,
+    .destroy = LoaderDestroyCb,
+    .message = LoaderMessageCb,
+  };
+
+  // Runs the main loop.
+  return service_loader_run(argc, argv, "appfw", &callback, NULL);
+}
+ * @endcode
+ */
 int service_loader_run(int argc, char **argv, const char *name,
                        service_loader_lifecycle_callback_s *callback,
                        void *user_data);
 
-int service_loader_quit(void);
+/**
+ * @brief Exits the main loop of the service loader.
+ * @details The main loop of the service loader stops and the service_loader_destroy_cb() callback function is called.
+ * @since_tizen 10.0
+ * @see service_loader_run()
+ * @see service_loader_destroy_cb()
+ *
+ * @code
+#include <service_loader.h>
+
+static void LoaderCreateCb(void* user_data) {
+  // Exits the main loop.
+  service_loader_exit();
+}
+
+static void LoaderDestroyCb(void* user_data) {
+  // ...
+}
+
+static void LoaderMessageCb(const char* sender, bundle* envelope, void* user_data) {
+  // ...
+}
+
+int main(int argc, char** argv) {
+  service_loader_lifecycle_callback_s callback = {
+    .create = LoaderCreateCb,
+    .destroy = LoaderDestroyCb,
+    .message = LoaderMessageCb,
+  };
+
+  return service_loader_run(argc, argv, "appfw", &callback, NULL);
+}
+ * @endcode
+ */
+void service_loader_quit(void);
+
+/**
+ * @brief Sends the message to the main loop of the service loader.
+ * @details The envelope will be delivered to the main loop of the service loader.
+ *          The service_loader_message_cb() will be invoked.
+ * @since_tizen 10.0
+ * @param[in] envelope The envelope of the message
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #SERVICE_LOADER_ERROR_NONE Successful
+ * @retval #SERVICE_LOADER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SERVICE_LOADER_ERROR_INVALID_CONTEXT Invalid context
+ * @see service_loader_message_cb()
+ *
+ * @code
+#include <service_loader.h>
+#include <dlog.h>
+
+#undef LOG_TAG
+#define LOG_TAG "TEST"
+
+static void LoaderMessageCb(const char* sender, bundle* envelope, void* user_data) {
+  char* message = nullptr;
+
+  if (bundle_get_str(envelope, "MESSAGE", &message) == BUNDLE_ERROR_NONE) {
+    LOGD("sender=%s, message=%s", sender, message);
+  }
+}
 
+static void SendMessage(const char* message) {
+  bundle* envelope = bundle_create();
+  if (envelope == nullptr) {
+    LOGE("Failed to create bundle");
+    return;
+  }
+
+  bundle_add_str(envelope, "MESSAGE", message);
+  int ret = service_loader_send_message(envelope);
+  if (ret != SERVICE_LOADER_ERROR_NONE) {
+    LOGE("Failed to send message to loader. error=%d", ret);
+  }
+
+  bundle_free(envelope);
+}
+ * @endcode
+ */
 int service_loader_send_message(bundle *envelope);
 
 #ifdef __cplusplus

diff --git a/src/stub_service_loader.cc b/src/stub_service_loader.cc
index 83e95dc8445e717f59fe9e533bbf7fd10e77b31c..1871a88700b4d7a60e1b8142db55f794d1b01284 100644 (file)
--- a/src/stub_service_loader.cc
+++ b/src/stub_service_loader.cc
@@ -98,11 +98,14 @@ API int service_loader_run(int argc, char** argv, const char* name,
   return SERVICE_LOADER_ERROR_NONE;
 }
 
-API int service_loader_quit(void) {
-  if (!::context) return SERVICE_LOADER_ERROR_INVALID_CONTEXT;
+API void service_loader_quit(void) {
+  if (!::context) {
+    set_last_result(SERVICE_LOADER_ERROR_INVALID_CONTEXT);
+    return;
+  }
 
   ::context->Quit();
-  return SERVICE_LOADER_ERROR_NONE;
+  set_last_result(SERVICE_LOADER_ERROR_NONE);
 }
 
 API int service_loader_send_message(bundle* envelope) {