Add API descriptions

Change-Id: Ie4d1329ac4631e6ed54d7027519c689085378137
Signed-off-by: Mu-Woong Lee <muwoong.lee@samsung.com>

diff --git a/doc/job_scheduler_internal_doc.h b/doc/job_scheduler_internal_doc.h
new file mode 100644 (file)
index 0000000..95cccf9
--- /dev/null
+++ b/doc/job_scheduler_internal_doc.h
@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2017 Samsung Electronics Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @ingroup            CAPI_CONTEXT_FRAMEWORK
+ * @defgroup   CAPI_CONTEXT_JOB_SCHEDULER_INTERNAL_MODULE Job Scheduler (Internal)
+ *
+ * @brief              Job Schdeuler Internal API
+ *
+ * @section            CAPI_CONTEXT_JOB_SCHEDULER_INTERNAL_MODULE_HEADER Required Header
+ *                             \#include <job_scheduler_internal.h>
+ *
+ * @section            CAPI_CONTEXT_JOB_SCHEDULER_INTERNAL_MODULE_OVERVIEW Overview
+ *
+ * TBD
+ *
+ */

diff --git a/include/job_scheduler_internal.h b/include/job_scheduler_internal.h
index 8ae0f4eb1c4ca2c99cfd697f9a8b1337b2c7653b..11c835765f2324a692d023db12866317876f4185 100644 (file)
--- a/include/job_scheduler_internal.h
+++ b/include/job_scheduler_internal.h
@@ -20,7 +20,6 @@
 #include <glib.h>
 #include <tizen.h>
 #include <bundle.h>
-#include <app_control.h>
 #include <job_scheduler_types_internal.h>
 
 #ifdef __cplusplus
@@ -28,113 +27,423 @@ extern "C"
 {
 #endif
 
+/**
+ * @addtogroup CAPI_CONTEXT_JOB_SCHEDULER_INTERNAL_MODULE
+ * @{
+ */
+
+/**
+ * @brief      Job scheduler handle.
+ */
 typedef struct _ctx_sched_s* ctx_sched_h;
 
+/**
+ * @brief      Container of data describing a job.
+ */
 typedef struct _ctx_sched_job_s* ctx_sched_job_h;
 
+/**
+ * @brief      Container of data defining a context that can be used as a trigger or a requirement.
+ */
 typedef struct _ctx_sched_job_context_s* ctx_sched_job_context_h;
 
-
+/**
+ * @brief      Called for each registered job.
+ * @param[in]  scheduler       TBD
+ * @param[in]  job                     TBD
+ * @param[in]  user_data       TBD
+ * @return     @c true to continue to iterate, otherwise @c false.
+ */
 typedef bool (*ctx_sched_foreach_job_cb)(ctx_sched_h scheduler, ctx_sched_job_h job, void* user_data);
 
-typedef bool (*ctx_sched_stop_job_cb)(ctx_sched_h scheduler, ctx_sched_job_h job, void* user_data);
+/**
+ * @brief      Called when a job needs to be stopped.
+ * @details In some reason, the device may no longer allow executions of scheduled jobs.
+ *                     This function is invoked to notify such circumstances.
+ * @param[in]  scheduler       TBD
+ * @param[in]  job                     TBD
+ * @param[in]  user_data       TBD
+ */
+typedef void (*ctx_sched_stop_job_cb)(ctx_sched_h scheduler, ctx_sched_job_h job, void* user_data);
 
 
+/**
+ * @brief      Creates a job scheduler handle.
+ * @param[out] scheduler       TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_create(ctx_sched_h* scheduler);
 
+/**
+ * @brief      Releases the resources allocated for a job scheduler handle.
+ * @param[in]  scheduler       TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_destroy(ctx_sched_h scheduler);
 
 
+/**
+ * @brief      Schedules a job.
+ * @details    This internally registers the job using ctx_sched_add_job() and starts it using ctx_sched_start_job().
+ * @param[in]  scheduler       TBD
+ * @param[in]  job                     TBD
+ * @param[out] job_id          TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_schedule(ctx_sched_h scheduler, ctx_sched_job_h job, int* job_id);
 
+/**
+ * @brief      Cancels a scheduled job.
+ * @details    This internally stops the job using ctx_sched_stop_job() and unregisters it using ctx_sched_remove_job().
+ * @param[in]  scheduler       TBD
+ * @param[in]  job_id          TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_cancel(ctx_sched_h scheduler, int job_id);
 
+/**
+ * @brief      Cancels all scheduled jobs.
+ * @param[in]  scheduler       TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_cancel_all(ctx_sched_h scheduler);
 
 
+/**
+ * @brief      Registers a job.
+ * @param[in]  scheduler       TBD
+ * @param[in]  job                     TBD
+ * @param[out] job_id          TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_add_job(ctx_sched_h scheduler, ctx_sched_job_h job, int* job_id);
 
+/**
+ * @brief      Starts a job
+ * @param[in]  scheduler       TBD
+ * @param[in]  job_id          TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_start_job(ctx_sched_h scheduler, int job_id);
 
+/**
+ * @brief      Stops a job
+ * @param[in]  scheduler       TBD
+ * @param[in]  job_id          TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_stop_job(ctx_sched_h scheduler, int job_id);
 
+/**
+ * @brief      Unregisters a job
+ * @param[in]  scheduler       TBD
+ * @param[in]  job_id          TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_remove_job(ctx_sched_h scheduler, int job_id);
 
 
+/**
+ * @brief      Gets a job information handle.
+ * @param[in]  scheduler       TBD
+ * @param[in]  job_id          TBD
+ * @param[out] job                     TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_get_job(ctx_sched_h scheduler, int job_id, ctx_sched_job_h* job);
 
+/**
+ * @brief      Gets all job information handles. Synchronous.
+ * @param[in]  scheduler       TBD
+ * @param[in]  callback        TBD
+ * @param[in]  user_data       TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_foreach_job(ctx_sched_h scheduler, ctx_sched_foreach_job_cb callback, void* user_data);
 
 
+/**
+ * @brief      Sets the callback function to be called when a job needs to be stopped.
+ * @param[in]  scheduler       TBD
+ * @param[in]  callback        TBD
+ * @param[in]  user_data       TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_set_stop_job_cb(ctx_sched_h scheduler, ctx_sched_stop_job_cb callback, void* user_data);
 
 
+/**
+ * @brief      Declares a custom context that can be used as a trigger or a requirement by other applications.
+ * @param[in]  scheduler       TBD
+ * @param[in]  uri                     TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_declare_context(ctx_sched_h scheduler, const char* uri);
 
+/**
+ * @brief      Retracts a custom context declared by the current application.
+ * @param[in]  scheduler       TBD
+ * @param[in]  uri                     TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_undeclare_context(ctx_sched_h scheduler, const char* uri);
 
+/**
+ * @brief      Publishes a custom context data corresponding to a URI declared using ctx_sched_declare_context().
+ * @param[in]  scheduler               TBD
+ * @param[in]  uri                             TBD
+ * @param[in]  json_payload    TBD
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_publish_context_json(ctx_sched_h scheduler, const char* uri, const char* json_payload);
 
 
+/**
+ * @brief      Creates a periodic job handle.
+ * @param[in]  interval        Periodic interval
+ * @param[in]  anchor          Reference time that the periodic timer starts with
+ * @param[out] job                     Job handle
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_create_periodic(unsigned int interval, time_t anchor, ctx_sched_job_h* job);
 
+/**
+ * @brief      Creates an on-demand job handle.
+ * @param[out] job                     Job handle
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_create_on_demand(ctx_sched_job_h* job);
 
+/**
+ * @brief      Releases the resources allocated for a job handle.
+ * @param[in]  job                     Job handle
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_destroy(ctx_sched_job_h job);
 
 
+/**
+ * @brief      Adds a trigger context to a job.
+ * @param[in]  job                     Job handle
+ * @param[in]  trigger         Trigger context
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_add_trigger(ctx_sched_job_h job, ctx_sched_job_context_h trigger);
 
+/**
+ * @brief      Adds a requirement context to a job.
+ * @param[in]  job                     Job handle
+ * @param[in]  requirement     Requirement context
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_add_requirement(ctx_sched_job_h job, ctx_sched_job_context_h requirement);
 
+/**
+ * @brief      Sets the timeout of a requirement context.
+ * @param[in]  job                     Job handle
+ * @param[in]  timeout         Timeout (ms)
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_set_requirement_timeout(ctx_sched_job_h job, unsigned int timeout);
 
+/**
+ * @brief      Sets a job to be automatically scheduled after the device reboots.
+ * @param[in]  job                     Job handle
+ * @param[in]  persistent      @c true, if the job needs to be automatically scheduled
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_set_persistent(ctx_sched_job_h job, bool persistent);
 
+/**
+ * @brief      Sets a job not to be repeated.
+ * @param[in]  job                     Job handle
+ * @param[in]  one_time        @c true, if the job does not need to be repeated
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_set_one_time(ctx_sched_job_h job, bool one_time);
 
-int ctx_sched_job_set_app_control(ctx_sched_job_h job, app_control_h app_control);
-
+/**
+ * @brief      Sets the app-control that will be called when the job's execution criteria is satisfied.
+ * @param[in]  job                     Job handle
+ * @param[in]  app_control     Serialized app-control
+ * @return     @c 0 on success, otherwise a negative error value
+ */
+int ctx_sched_job_set_app_control(ctx_sched_job_h job, bundle* app_control);
+
+/**
+ * @brief      Sets the DBus method that will be called when the job's execution criteria is satisfied.
+ * @param[in]  job                     Job handle
+ * @param[in]  bus_name        DBus destination
+ * @param[in]  object_path     DBus object path
+ * @param[in]  interface       DBus interface
+ * @param[in]  method          DBus method name
+ * @param[in]  parameters      DBus parameters
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_set_dbus(ctx_sched_job_h job, const char* bus_name,
                const char* object_path, const char* interface, const char* method, GVariant* parameters);
 
+/**
+ * @brief      Attaches the bundle that can be retrieved using ctx_sched_job_get_bundle().
+ * @param[in]  job                     Job handle
+ * @param[in]  user_bundle     Bundle
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_set_bundle(ctx_sched_job_h job, bundle* user_bundle);
 
 
+/**
+ * @brief      Checks whether a job is started or not.
+ * @param[in]  job                     Job handle
+ * @param[out] started         @c true, if the job is started
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_is_started(ctx_sched_job_h job, bool* started);
 
+/**
+ * @brief      Gets the ID of a job
+ * @param[in]  job                     Job handle
+ * @param[out] job_id          Job ID
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_get_id(ctx_sched_job_h job, int* job_id);
 
+/**
+ * @brief      Gets the bundle attached to a job
+ * @param[in]  job                     Job handle
+ * @param[out] user_bundle     Bundle
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_get_bundle(ctx_sched_job_h job, bundle** user_bundle);
 
 
+/**
+ * @brief      Checks whether the trigger context corresponding to a URI is supported.
+ * @param[in]  uri                     URI
+ * @param[out] supported       @c true, if the corresponding context is supported as a trigger
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_trigger_is_supported(const char* uri, bool* supported);
 
+/**
+ * @brief      Creates a trigger context handle.
+ * @param[in]  uri                     URI
+ * @param[out] job_context     Trigger context handle
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_trigger_create(const char* uri, ctx_sched_job_context_h* job_context);
 
+/**
+ * @brief      Checks whether the requirement context corresponding to a URI is supported.
+ * @param[in]  uri                     URI
+ * @param[out] supported       @c true, if the corresponding context is supported as a requirement
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_requirement_is_supported(const char* uri, bool* supported);
 
+/**
+ * @brief      Creates a requirement context handle.
+ * @param[in]  uri                     URI
+ * @param[in]  optional        @c true, if the requirement is optional
+ * @param[out] job_context     Requirement context handle
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_requirement_create(const char* uri, bool optional, ctx_sched_job_context_h* job_context);
 
-int ctx_sched_job_context_prepare_attribute(ctx_sched_job_context_h job_context, const char* attribute);
 
+/**
+ * @brief      Prepares an attribute of a context.
+ * @param[in]  job_context     Context handle
+ * @param[in]  attribute       Name of attribute
+ * @return     @c 0 on success, otherwise a negative error value
+ */
+int ctx_sched_job_context_prepare_attribute(ctx_sched_job_context_h job_context, const char* attribute);
 
+/**
+ * @brief      Adds an equal-to condition of a context attribute.
+ * @param[in]  job_context     Context handle
+ * @param[in]  attribute       Name of attribute
+ * @param[in]  value           Value to be compared
+ * @return     @c 0 on success, otherwise a negative error value
+ * @pre                ctx_sched_job_context_prepare_attribute()
+ */
 int ctx_sched_job_context_attribute_add_eq_int(ctx_sched_job_context_h job_context, const char* attribute, int value);
 
+/**
+ * @brief      Adds an equal-to condition of a context attribute.
+ * @param[in]  job_context     Context handle
+ * @param[in]  attribute       Name of attribute
+ * @param[in]  value           Value to be compared
+ * @return     @c 0 on success, otherwise a negative error value
+ * @pre                ctx_sched_job_context_prepare_attribute()
+ */
 int ctx_sched_job_context_attribute_add_eq_str(ctx_sched_job_context_h job_context, const char* attribute, const char* value);
 
+/**
+ * @brief      Adds a not-equal-to condition of a context attribute.
+ * @param[in]  job_context     Context handle
+ * @param[in]  attribute       Name of attribute
+ * @param[in]  value           Value to be compared
+ * @return     @c 0 on success, otherwise a negative error value
+ * @pre                ctx_sched_job_context_prepare_attribute()
+ */
 int ctx_sched_job_context_attribute_add_ne_int(ctx_sched_job_context_h job_context, const char* attribute, int value);
 
+/**
+ * @brief      Adds a not-equal-to condition of a context attribute.
+ * @param[in]  job_context     Context handle
+ * @param[in]  attribute       Name of attribute
+ * @param[in]  value           Value to be compared
+ * @return     @c 0 on success, otherwise a negative error value
+ * @pre                ctx_sched_job_context_prepare_attribute()
+ */
 int ctx_sched_job_context_attribute_add_ne_str(ctx_sched_job_context_h job_context, const char* attribute, const char* value);
 
+/**
+ * @brief      Adds a greater-than condition of a context attribute.
+ * @param[in]  job_context     Context handle
+ * @param[in]  attribute       Name of attribute
+ * @param[in]  value           Value to be compared
+ * @return     @c 0 on success, otherwise a negative error value
+ * @pre                ctx_sched_job_context_prepare_attribute()
+ */
 int ctx_sched_job_context_attribute_set_gt_int(ctx_sched_job_context_h job_context, const char* attribute, int value);
 
+/**
+ * @brief      Adds a greater-than-or-equal-to condition of a context attribute.
+ * @param[in]  job_context     Context handle
+ * @param[in]  attribute       Name of attribute
+ * @param[in]  value           Value to be compared
+ * @return     @c 0 on success, otherwise a negative error value
+ * @pre                ctx_sched_job_context_prepare_attribute()
+ */
 int ctx_sched_job_context_attribute_set_ge_int(ctx_sched_job_context_h job_context, const char* attribute, int value);
 
+/**
+ * @brief      Adds a less-than condition of a context attribute.
+ * @param[in]  job_context     Context handle
+ * @param[in]  attribute       Name of attribute
+ * @param[in]  value           Value to be compared
+ * @return     @c 0 on success, otherwise a negative error value
+ * @pre                ctx_sched_job_context_prepare_attribute()
+ */
 int ctx_sched_job_context_attribute_set_lt_int(ctx_sched_job_context_h job_context, const char* attribute, int value);
 
+/**
+ * @brief      Adds a less-than-or-equal-to condition of a context attribute.
+ * @param[in]  job_context     Context handle
+ * @param[in]  attribute       Name of attribute
+ * @param[in]  value           Value to be compared
+ * @return     @c 0 on success, otherwise a negative error value
+ * @pre                ctx_sched_job_context_prepare_attribute()
+ */
 int ctx_sched_job_context_attribute_set_le_int(ctx_sched_job_context_h job_context, const char* attribute, int value);
 
+/**
+ * @brief      Releases the resources allocated for a job context.
+ * @param[in]  job_context     Context handle
+ * @return     @c 0 on success, otherwise a negative error value
+ */
 int ctx_sched_job_context_destroy(ctx_sched_job_context_h job_context);
 
 
@@ -147,8 +456,12 @@ int ctx_sched_job_context_set_disjunction(ctx_sched_job_context_h job_context, b
 int ctx_sched_job_context_attribute_set_disjunction(ctx_sched_job_context_h job_context, const char* attribute, bool disjunction);
 
 
+/**
+ * @}
+ */
+
 #ifdef __cplusplus
 }
 #endif
 
-#endif
+#endif /* __CAPI_CONTEXT_JOB_SCHEDULER_INTERNAL_H__ */