include/job_scheduler.h

   1 /*
   2  * Copyright (c) 2017 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_APPFW_JOB_SCHEDULER_H__
  18 #define __TIZEN_APPFW_JOB_SCHEDULER_H__
  19
  20 #include <job_error.h>
  21 #include <job_info.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @addtogroup CAPI_JOB_SCHEDULER_MODULE
  29  * @{
  30  */
  31
  32 /**
  33  * @brief The job service handle.
  34  * @since_tizen 4.0
  35  */
  36 typedef struct job_service_s *job_service_h;
  37
  38 /**
  39  * @brief Called when the job starts.
  40  * @since_tizen 4.0
  41  * @remarks The @a job_info MUST NOT be deallocated by the application.
  42  *          The @a job_info is managed by the platform and is valid only in the callback.
  43  * @param[in]   job_info        The job info handle
  44  * @param[in]   user_data       The user data passed from the callback registration function
  45  * @see    job_scheduler_service_add()
  46  * @see    #job_service_callback_s
  47  */
  48 typedef void (*job_service_start_cb)(job_info_h job_info, void *user_data);
  49
  50 /**
  51  * @brief Called when the job stops.
  52  * @since_tizen 4.0
  53  * @remarks The @a job_info MUST not be deallocated by the application.
  54  *          The @a job_info is managed by the platform and is valid only in the callback.
  55  * @param[in]   job_info        The job info handle
  56  * @param[in]   user_data       The user data passed from the callback registration function
  57  * @see    job_scheduler_service_add()
  58  * @see    #job_service_callback_s
  59  */
  60 typedef void (*job_service_stop_cb)(job_info_h job_info, void *user_data);
  61
  62 /**
  63  * @brief The structure type containing the set of callback functions for handling jobs.
  64  * @details It is one of the input parameter of the job_scheduler_service_add() function.
  65  * @since_tizen 4.0
  66  * @see    job_scheduler_service_add()
  67  * @see    job_service_start_cb()
  68  * @see    job_service_stop_cb()
  69  */
  70 typedef struct {
  71         job_service_start_cb start;     /**< This callback function is called at the start of the job. */
  72         job_service_stop_cb stop;       /**< This callback function is called at the stop of the job. */
  73 } job_service_callback_s;
  74
  75 /**
  76  * @brief Called to retrieve the job information.
  77  * @since_tizen 4.0
  78  * @remarks The @a job_info must not be deallocated by the application.
  79  * @param[in]   job_info        The job_info handle
  80  * @param[in]   user_data       The user data passed from the foreach function
  81  * @return @c true continue with the next iteration of the loop,
  82  *         otherwise @c false to break out of the loop
  83  * @pre    job_scheduler_foreach_job() will invoke this callback.
  84  * @see    job_scheduler_foreach_job()
  85  */
  86 typedef bool (*job_scheduler_foreach_job_cb)(job_info_h job_info, void *user_data);
  87
  88 /**
  89  * @brief Initializes the job scheduler.
  90  * @since_tizen 4.0
  91  * @return @c 0 on success,
  92  *         otherwise a negative error value
  93  * @retval #JOB_ERROR_NONE              Successful
  94  * @retval #JOB_ERROR_IO_ERROR          IO error
  95  * @retval #JOB_ERROR_OUT_OF_MEMORY     Out of memory
  96  * @see    job_scheduler_finish()
  97  */
  98 int job_scheduler_init(void);
  99
 100 /**
 101  * @brief Finalizes the job scheduler.
 102  * @since_tizen 4.0
 103  * @return @c 0 on success,
 104  *         otherwise a negative error value
 105  * @retval #JOB_ERROR_NONE              Successful
 106  * @retval #JOB_ERROR_NOT_INITIALIZED   Not initialized
 107  * @see    job_scheduler_init()
 108  */
 109 int job_scheduler_finish(void);
 110
 111 /**
 112  * @brief Schedules the job.
 113  * @since_tizen 4.0
 114  * @privlevel   public
 115  * @privilege   %http://tizen.org/privilege/appmanager.launch
 116  * @param[in]   job_info        The job info handle
 117  * @param[in]   job_id          The ID of the job
 118  * @return @c 0 on success,
 119  *         otherwise a negative error value
 120  * @retval #JOB_ERROR_NONE              Successful
 121  * @retval #JOB_ERROR_INVALID_PARAMETER Invalid parameter
 122  * @retval #JOB_ERROR_NOT_INITIALIZED   Not initialized
 123  * @retval #JOB_ERROR_IO_ERROR          IO error
 124  * @retval #JOB_ERROR_ALREADY_EXIST     Already exist
 125  * @retval #JOB_ERROR_OUT_OF_MEMORY     Out of memory
 126  * @retval #JOB_ERROR_PERMISSION_DENIED Permission denied
 127  * @pre    job_scheduler_init() MUST be called.
 128  * @see    job_scheduler_init()
 129  * @see    job_info_create()
 130  */
 131 int job_scheduler_schedule(job_info_h job_info, const char *job_id);
 132
 133 /**
 134  * @brief Cancels the scheduled job.
 135  * @since_tizen 4.0
 136  * @param[in]   job_id          The ID of the scheduled job
 137  * @return @c 0 on success,
 138  *         otherwise a negative error value
 139  * @retval #JOB_ERROR_NONE              Successful
 140  * @retval #JOB_ERROR_INVALID_PARAMETER Invalid parameter
 141  * @retval #JOB_ERROR_NOT_INITIALIZED   Not initialized
 142  * @retval #JOB_ERROR_IO_ERROR          IO error
 143  * @retval #JOB_ERROR_NO_SUCH_JOB       No such job
 144  * @pre    job_scheduler_init() MUST be called.
 145  * @see    job_scheduler_init()
 146  */
 147 int job_scheduler_cancel(const char *job_id);
 148
 149 /**
 150  * @brief Cancels all scheduled jobs.
 151  * @since_tizen 4.0
 152  * @return @c 0 on success,
 153  *         otherwise a negative error value
 154  * @retval #JOB_ERROR_NONE              Successful
 155  * @retval #JOB_ERROR_NOT_INITIALIZED   Not initialized
 156  * @retval #JOB_ERROR_IO_ERROR          IO error
 157  * @pre    job_scheduler_init() MUST be called.
 158  * @see    job_scheduler_init()
 159  */
 160 int job_scheduler_cancel_all(void);
 161
 162 /**
 163  * @brief Notifies that the job is finished.
 164  * @since_tizen 4.0
 165  * @remarks If the job has been launched, the system kept awake for a while.
 166  *          It is highly recommended to notify that the job is done,
 167  *          the system thus knows it does not need to be kept awake.
 168  * @param[in]   job_id          The ID of the scheduled job
 169  * @return @c 0 on success,
 170  *         otherwise a negative error value
 171  * @retval #JOB_ERROR_NONE              Successful
 172  * @retval #JOB_ERROR_INVALID_PARAMETER Invalid parameter
 173  * @retval #JOB_ERROR_NOT_INITIALIZED   Not initialized
 174  * @retval #JOB_ERROR_NO_SUCH_JOB       No such job
 175  * @retval #JOB_ERROR_IO_ERROR          IO error
 176  * @pre    job_scheduler_init() MUST be called.
 177  * @see    job_scheduler_init()
 178  */
 179 int job_scheduler_notify_job_finished(const char *job_id);
 180
 181 /**
 182  * @brief Retrieves all scheduled jobs.
 183  * @since_tizen 4.0
 184  * @param[in]   callback        The iteration callback function
 185  * @param[in]   user_data       The user data to be passed to the callback function
 186  * @return @c 0 on success,
 187  *         otherwise a negative error value
 188  * @retval #JOB_ERROR_NONE              Successful
 189  * @retval #JOB_ERROR_INVALID_PARAMETER Invalid parameter
 190  * @retval #JOB_ERROR_NOT_INITIALIZED   Not initialized
 191  * @retval #JOB_ERROR_NO_SUCH_JOB       No scheduled jobs
 192  * @pre    job_scheduler_init() MUST be called.
 193  * @see    job_scheduler_init()
 194  */
 195 int job_scheduler_foreach_job(job_scheduler_foreach_job_cb callback, void *user_data);
 196
 197 /**
 198  * @brief Adds job service handler for receiving the information of the scheduled job.
 199  * @since_tizen 4.0
 200  * @remarks The @a job_service handle should be released using job_scheduler_service_remove().
 201  * @param[in]   job_id          The ID of the job
 202  * @param[in]   callback        The set of callback functions to handle jobs
 203  * @param[in]   user_data       The user data to be passed to the callback function
 204  * @param[out]  job_service     The job service handle
 205  * @return @c 0 on success,
 206  *         otherwise a negative error value
 207  * @retval #JOB_ERROR_NONE              Successful
 208  * @retval #JOB_ERROR_INVALID_PARAMETER Invalid parameter
 209  * @retval #JOB_ERROR_NOT_INITIALIZED   Not initialized
 210  * @retval #JOB_ERROR_OUT_OF_MEMORY     Out of memory
 211  * @pre    job_scheduler_init() MUST be called.
 212  * @see    job_scheduler_init()
 213  * @see    job_scheduler_service_remove()
 214  * @see    job_service_start_cb()
 215  * @see    job_service_stop_cb()
 216  * @see    job_scheduler_job_finished()
 217  * @see    #job_service_callback_s
 218  */
 219 int job_scheduler_service_add(const char *job_id, job_service_callback_s *callback, void *user_data, job_service_h *job_service);
 220
 221 /**
 222  * @brief Removes registered job service handler.
 223  * @since_tizen 4.0
 224  * @param[in]   job_service     The job service handle
 225  * @return @c 0 on success,
 226  *         otherwise a negative error value
 227  * @retval #JOB_ERROR_NONE              Successful
 228  * @retval #JOB_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #JOB_ERROR_NOT_INITIALIZED   Not initialized
 230  * @pre    job_scheduler_init() MUST be called.
 231  * @see    job_scheduler_init()
 232  * @see    job_scheduler_service_add()
 233  */
 234 int job_scheduler_service_remove(job_service_h job_service);
 235
 236 /**
 237  * @}
 238  */
 239
 240 #ifdef __cplusplus
 241 }
 242 #endif
 243
 244 #endif /* __TIZEN_APPFW_JOB_SCHEDULER_H__ */