include/component_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 #ifndef __TIZEN_APPFW_COMPONENT_CONTEXT_H__
  18 #define __TIZEN_APPFW_COMPONENT_CONTEXT_H__
  19
  20 #include <stdbool.h>
  21 #include <sys/types.h>
  22 #include <tizen.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file component_context.h
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_COMPONENT_CONTEXT_MODULE
  34  * @{
  35  */
  36
  37
  38 /**
  39  * @brief Component context handle.
  40  * @since_tizen 5.5
  41  */
  42 typedef void *component_context_h;
  43
  44 /**
  45  * @brief Enumeration for the component state.
  46  * @since_tizen 5.5
  47  */
  48 typedef enum {
  49         COMPONENT_STATE_INITIALIZED,    /**< The initialized state. The state that the component is constructed but the callback for creating a component is not called yet. */
  50         COMPONENT_STATE_CREATED,        /**< The created state. This state that the creating callback is called.  */
  51         COMPONENT_STATE_STARTED,        /**< The started state. This state that the starting callback is called. */
  52         COMPONENT_STATE_RESUMED,        /**< The resumed state. This state that the resuming callback is called. */
  53         COMPONENT_STATE_PAUSED,         /**< The paused state. This state that the pausing callback is called. */
  54         COMPONENT_STATE_DESTROYED,      /**< The destroyed state. This state that right before the destroying callback is called. */
  55 } component_state_e;
  56
  57 /**
  58  * @brief Destroys the component context handle and releases all its resources.
  59  * @since_tizen 5.5
  60  *
  61  * @param[in]   handle          The component context handle
  62  * @return      @c 0 on success,
  63  *              otherwise a negative error value
  64  * @retval #COMPONENT_MANAGER_ERROR_NONE Successful
  65  * @retval #COMPONENT_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
  66  */
  67 int component_context_destroy(component_context_h handle);
  68
  69 /**
  70  * @brief Gets the application ID of the component.
  71  * @since_tizen 5.5
  72  * @remarks You MUST release @c app_id using free().
  73  *
  74  * @param[in]   handle          The component context handle
  75  * @param[out]  app_id          The application ID
  76  * @return      @c 0 on success,
  77  *              otherwise a negative error value
  78  * @retval #COMPONENT_MANAGER_ERROR_NONE Successful
  79  * @retval #COMPONENT_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
  80  * @retval #COMPONENT_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
  81  */
  82 int component_context_get_app_id(component_context_h handle, char **app_id);
  83
  84 /**
  85  * @brief Gets the ID of the component.
  86  * @since_tizen 5.5
  87  * @remarks You MUST release @c comp_id using free().
  88  *
  89  * @param[in]   handle          The component context handle
  90  * @param[out]  component_id    The component ID
  91  * @return      @c 0 on success,
  92  *              otherwise a negative error value
  93  * @retval #COMPONENT_MANAGER_ERROR_NONE Successful
  94  * @retval #COMPONENT_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
  95  * @retval #COMPONENT_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
  96  */
  97 int component_context_get_component_id(component_context_h handle, char **component_id);
  98
  99 /**
 100  * @brief Gets the instance ID of the component.
 101  * @since_tizen 5.5
 102  * @remarks You MUST release @c instance_id using free().
 103  *
 104  * @param[in]   handle          The component context handle
 105  * @param[out]  instance_id     The instance ID
 106  * @return      @c 0 on success,
 107  *              otherwise a negative error value
 108  * @retval #COMPONENT_MANAGER_ERROR_NONE Successful
 109  * @retval #COMPONENT_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 110  * @retval #COMPONENT_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
 111  */
 112 int component_context_get_instance_id(component_context_h handle, char **instance_id);
 113
 114 /**
 115  * @brief Gets the state of the component.
 116  * @since_tizen 5.5
 117  *
 118  * @param[in]   handle          The component context handle
 119  * @param[out]  state           The component state
 120  * @return      @c 0 on success,
 121  *              otherwise a negative error value
 122  * @retval #COMPONENT_MANAGER_ERROR_NONE Successful
 123  * @retval #COMPONENT_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 124  */
 125 int component_context_get_component_state(component_context_h handle, component_state_e *state);
 126
 127 /**
 128  * @brief Checks whether the component is terminated or not.
 129  * @since_tizen 5.5
 130  *
 131  * @param[in]   handle          The component context handle
 132  * @param[out]  terminated      @c true if the component is terminated, \n
 133  *                              otherwise @c false if the component is running
 134  * @return      @c 0 on success,
 135  *              otherwise a negative error value
 136  * @retval #COMPONENT_MANAGER_ERROR_NONE Successful
 137  * @retval #COMPONENT_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 138  * @retval #COMPONENT_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
 139  * @retval #COMPONENT_MANAGER_ERROR_IO_ERROR I/O error
 140  */
 141 int component_context_is_terminated(component_context_h handle, bool *terminated);
 142
 143 /**
 144  * @brief Checks whether the component is running as sub component of the group.
 145  * @since_tizen 5.5
 146  *
 147  * @param[in]   handle          The component context handle
 148  * @param[out]  is_subcomponent @c true if the sub component of the group, \n
 149  *                              otherwise @c false if the main component of the group
 150  * @return      @c 0 on success,
 151  *              otherwise a negative error value
 152  * @retval #COMPONENT_MANAGER_ERROR_NONE Successful
 153  * @retval #COMPONENT_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 154  */
 155 int component_context_is_subcomponent(component_context_h handle, bool *is_subcomponent);
 156
 157 /**
 158  * @brief Clones the component context handle.
 159  * @since_tizen 5.5
 160  * @remarks The @a clone should be released using component_context_destroy().
 161  *
 162  * @param[out]  clone           A newly created component context handle, if cloning is successful
 163  * @param[in]   handle          The component context handle
 164  * @return      @c 0 on success,
 165  *              otherwise a negative error value
 166  * @retval #COMPONENT_MANAGER_ERROR_NONE Successful
 167  * @retval #COMPONENT_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 168  * @retval #COMPONENT_MANAGER_ERROR_OUT_OF_MEMORY Out of memory
 169  */
 170 int component_context_clone(component_context_h *clone, component_context_h handle);
 171
 172 /**
 173  * @}
 174  */
 175
 176 #ifdef __cplusplus
 177 }
 178 #endif
 179
 180 #endif /* __TIZEN_APPFW_COMPONENT_CONTEXT_H__ */