include/aul_comp_context.h

   1 /*
   2  * Copyright (c) 2019 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 #pragma once
  18
  19 #include <unistd.h>
  20 #include <stdbool.h>
  21
  22 #include <aul.h>
  23 #include <aul_comp_types.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @brief The component context handle.
  31  * @since_tizen 5.5
  32  */
  33 typedef struct aul_comp_context_s *aul_comp_context_h;
  34
  35 /**
  36  * @brief Called to get the component context for each component.
  37  * @since_tizen 5.5
  38  * @remarks You MUST NOT release @a handle using aul_comp_context_destroy().
  39  *
  40  * @param[in]   handle          The component context handle
  41  * @param[in]   user_data       The user data passed from the foreach function
  42  * @return      @c true to continue with the next iteration of the loop, \n
  43  *              otherwise @ false to break out of the loop
  44  * @see aul_comp_context_foreach_comp_context()
  45  */
  46 typedef bool (*aul_comp_context_cb)(aul_comp_context_h handle, void *user_data);
  47
  48 /**
  49  * @brief Retrieves all running components context.
  50  * @since_tizen 5.5
  51  * @privlevel public
  52  * @privilege %http://tizen.org/privilege/packagemanager.info
  53  *
  54  * @param[in]   callback        The callback function to invoke
  55  * @param[in]   user_data       The user data to be passed to the callback function
  56  * @return      @c 0 on success,
  57  *              otherwise a negative error value
  58  * @see aul_comp_context_cb()
  59  *
  60  * @remarks This function is only for App Framework internally.
  61  */
  62 int aul_comp_context_foreach_comp_context(aul_comp_context_cb callback,
  63                 void *user_data);
  64
  65 /**
  66  * @brief Gets the application ID of the component.
  67  * @since_tizen 5.5
  68  * @remarks You MUST NOT release @a app_id using free().
  69  *
  70  * @param[in]   handle          The component context handle
  71  * @param[out]  app_id          The application ID of the component
  72  * @return      @c 0 on success,
  73  *              otherwise a negative error value
  74  *
  75  * @remarks This function is only for App Framework internally.
  76  */
  77 int aul_comp_context_get_app_id(aul_comp_context_h handle, const char **app_id);
  78
  79 /**
  80  * @brief Gets the instance ID of the component.
  81  * @since_tizen 5.5
  82  * @remarks You MUST NOT release @a app_id using free().
  83  *
  84  * @param[in]   handle          The component context handle
  85  * @param[out]  instance_id     The instance ID of the component
  86  * @return      @c 0 on success,
  87  *              otherwise a negative error value
  88  *
  89  * @remarks This function is only for App Framework internally.
  90  */
  91 int aul_comp_context_get_instance_id(aul_comp_context_h handle,
  92                 const char **instance_id);
  93
  94 /**
  95  * @brief Gets the ID of the component.
  96  * @since_tizen 5.5
  97  * @remarks You MUST NOT release @a comp_id using free().
  98  *
  99  * @param[in]   handle          The component context handle
 100  * @param[out]  comp_id         The ID of the component
 101  * @return      @c 0 on success,
 102  *              otherwise a negative error value
 103  *
 104  * @remarks This function is only for App Framework internally.
 105  */
 106 int aul_comp_context_get_comp_id(aul_comp_context_h handle,
 107                 const char **comp_id);
 108
 109 /**
 110  * @brief Gets the type of the component.
 111  * @since_tizen 5.5
 112  * @remarks You MUST NOT release @a type using free().
 113  *
 114  * @param[in]   handle          The component context handle
 115  * @param[out]  type            The type of the component
 116  * @return      @c 0 on success,
 117  *              otherwise a negative error value
 118  *
 119  * @remarks This function is only for App Framework internally.
 120  */
 121 int aul_comp_context_get_type(aul_comp_context_h handle, const char **type);
 122
 123 /**
 124  * @brief Gets the process ID of the component.
 125  * @since_tizen 5.5
 126  *
 127  * @param[in]   handle          The component context handle
 128  * @param[out]  pid             The process ID of the component
 129  * @return      @c 0 on success,
 130  *              otherwise a negative error value
 131  *
 132  * @remarks This function is only for App Framework internally.
 133  */
 134 int aul_comp_context_get_pid(aul_comp_context_h handle, pid_t *pid);
 135
 136 /**
 137  * @brief Gets the status of the component.
 138  * @since_tizen 5.5
 139  *
 140  * @param[in]   handle          The component context handle
 141  * @param[out]  status          The status of the component
 142  * @return      @c 0 on success,
 143  *              otherwise a negative error value
 144  *
 145  * @see comp_status_e
 146  *
 147  * @remarks This function is only for App Framework internally.
 148  */
 149 int aul_comp_context_get_status(aul_comp_context_h handle, int *status);
 150
 151 /**
 152  * @brief Checks whether the component is sub component of the app group or not.
 153  * @since_tizen 5.5
 154  *
 155  * @param[in]   handle          The component context handle
 156  * @param[out]  is_sub_comp     @c true if the component is sub component, \n
 157  *                              otherwise @c false
 158  * @return      @c 0 on success,
 159  *              otherwise a negative error value
 160  *
 161  * @remarks This function is only for App Framework internally.
 162  */
 163 int aul_comp_context_is_sub_comp(aul_comp_context_h handle, bool *is_sub_comp);
 164
 165 /**
 166  * @brief Creates the component context handle.
 167  * @since_tizen 5.5
 168  * @privlevel public
 169  * @privilege %http://tizen.org/privilege/packagemanager.info
 170  * @remarks You MUST release @c clone using aul_comp_context_destroy().
 171  *
 172  * @param[in]   comp_id         The component ID
 173  * @param[out]  handle          The component context handle
 174  * @return      @c 0 on success,
 175  *              otherwise a negative error value
 176  *
 177  * @remarks This function is only for App Framework internally.
 178  * @see aul_comp_context_destroy()
 179  */
 180 int aul_comp_context_create(const char *comp_id, aul_comp_context_h *handle);
 181
 182 /**
 183  * @brief Creates the component context handle.
 184  * @since_tizen 5.5
 185  * @privlevel public
 186  * @privilege %http://tizen.org/privilege/packagemanager.info
 187  * @remarks You MUST release @c clone using aul_comp_context_destroy().
 188  *
 189  * @param[in]   comp_id         The component ID
 190  * @parma[in]   uid             The user ID
 191  * @param[out]  handle          The component context handle
 192  * @return      @c 0 on success,
 193  *              otherwise a negative error value
 194  *
 195  * @remarks This function is only for App Framework internally.
 196  * @see aul_comp_context_destroy()
 197  */
 198 int aul_comp_context_usr_create(const char *comp_id, uid_t uid,
 199                 aul_comp_context_h *handle);
 200
 201 /**
 202  * @brief Destroys the component context handle.
 203  * @since_tizen 5.5
 204  *
 205  * @param[in]   handle          The component context handle
 206  * @return      @c 0 on success,
 207  *              otherwise a negative error value
 208  *
 209  * @remarks This function is only for App Framework internally.
 210  */
 211 int aul_comp_context_destroy(aul_comp_context_h handle);
 212
 213 /**
 214  * @brief Clones the component context handle.
 215  * @since_tizen 5.5
 216  * @remarks You MUST release @c clone using aul_comp_context_destroy().
 217  *
 218  * @param[in]   handle          The component context handle
 219  * @param[out]  clone           A newly created component context handle, if sucessfully cloned
 220  * @return      @c 0 on success,
 221  *              otherwise a negative error value
 222  *
 223  * @remarks This function is only for App Framework internally.
 224  * @see aul_comp_context_destroy()
 225  */
 226 int aul_comp_context_clone(aul_comp_context_h handle,
 227                 aul_comp_context_h *clone);
 228
 229 /**
 230  * @brief Checks whether the component is running or not.
 231  * @since_tizen 5.5
 232  *
 233  * @param[in]   handle          The component context handle
 234  * @param[out]  running         @c true if the component is running, \n
 235  *                              otherwise @c false if not running
 236  * @return      @c 0 on success,
 237  *              otherwise a negative error value
 238  *
 239  * @remarks This function is only for App Framework internally.
 240  */
 241 int aul_comp_context_is_running(aul_comp_context_h handle, bool *running);
 242
 243 /**
 244  * @brief Sends the request for resuming the component.
 245  * @since_tizen 5.5
 246  * @privlevel public
 247  * @privilege %http://tizen.org/privilege/appmanager.launch
 248  *
 249  * @param[in]   handle          The component context handle
 250  * @return      @c 0 on success,
 251  *              otherwise a negative error value
 252  *
 253  * @remarks This function is only for App Framework internally.
 254  */
 255 int aul_comp_context_resume(aul_comp_context_h handle);
 256
 257 /**
 258  * @brief Sends the request for pausing the component.
 259  * @since_tizen 5.5
 260  * @privlevel public
 261  * @privilege %http://tizen.org/privilege/appmanager.launch
 262  *
 263  * @param[in]   handle          The component context handle
 264  * @return      @c 0 on success,
 265  *              otherwise a negative error value
 266  *
 267  * @remarks This function is only for App Framework internally.
 268  */
 269 int aul_comp_context_pause(aul_comp_context_h handle);
 270
 271 /**
 272  * @brief Sends the request for terminating the background component.
 273  * @since_tizen 5.5
 274  * @privlevel public
 275  * @privilege %http://tizen.org/privilege/appmanager.kill.bgapp
 276  *
 277  * @param[in]   handle          The component context handle
 278  * @return      @c 0 on success,
 279  *              otherwise a negative error value
 280  *
 281  * @remarks This function is only for App Framework internally.
 282  */
 283 int aul_comp_context_terminate_bg_comp(aul_comp_context_h handle);
 284
 285 /**
 286  * @brief Sends the request for terminating the running component.
 287  * @since_tizen 5.5
 288  * @privlevel platform
 289  * @privilege %http://tizen.org/privilege/appmanager.kill
 290  *
 291  * @param[in]   handle          The component context handle
 292  * @return      @c 0 on success,
 293  *              otherwise a negative error value
 294  *
 295  * @remarks This function is only for App Framework internally.
 296  */
 297 int aul_comp_context_terminate(aul_comp_context_h handle);
 298
 299 #ifdef __cplusplus
 300 }
 301 #endif