include/app_context.h

   1 /*
   2  * Copyright (c) 2011 - 2016 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
  18 #ifndef __TIZEN_APPFW_APP_CONTEXT_H
  19 #define __TIZEN_APPFW_APP_CONTEXT_H
  20
  21 #include <sys/types.h>
  22 #include <tizen.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file  app_context.h
  30  */
  31
  32 /**
  33  * @addtogroup  CAPI_APP_CONTEXT_MODULE
  34  * @{
  35  */
  36
  37
  38 /**
  39  * @brief  Application context handle.
  40  * @since_tizen  @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  41  */
  42 typedef struct app_context_s *app_context_h;
  43
  44
  45 /**
  46  * @brief  Enumeration for Application Context Event.
  47  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  48  */
  49 typedef enum {
  50         APP_CONTEXT_EVENT_LAUNCHED, /**< The application is launched */
  51         APP_CONTEXT_EVENT_TERMINATED, /**< The application is terminated */
  52 } app_context_event_e;
  53
  54
  55 /**
  56  * @brief Enumeration for the application state.
  57  * @since_tizen 3.0
  58  */
  59 typedef enum {
  60         APP_STATE_UNDEFINED, /**< The undefined state */
  61         APP_STATE_FOREGROUND, /**< The UI application is running in the foreground. */
  62         APP_STATE_BACKGROUND, /**< The UI application is running in the background. */
  63         APP_STATE_SERVICE, /**< The Service application is running. */
  64         APP_STATE_TERMINATED, /**< The application is terminated. */
  65 } app_state_e;
  66
  67
  68 /**
  69  * @brief  Destroys the application context handle and releases all its resources.
  70  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  71  * @param[in]   app_context  The application context handle
  72  * @return      @c 0 on success,
  73  *              otherwise a negative error value
  74  * @retval  #APP_MANAGER_ERROR_NONE               Successful
  75  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
  76  * @see app_manager_foreach_app_context()
  77  * @see app_manager_get_app_context()
  78  */
  79 int app_context_destroy(app_context_h app_context);
  80
  81
  82 /**
  83  * @deprecated Deprecated since 2.3.1. Use app_context_get_app_id() instead.
  84  * @brief    Gets the application ID with the given application context.
  85  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  86  * @remarks You must release @a package using free().
  87  * @param[in]   app_context  The application context
  88  * @param[out]  package      The application ID of the given application context
  89  * @return      @c 0 on success,
  90  *              otherwise a negative error value
  91  * @retval  #APP_MANAGER_ERROR_NONE               Successful
  92  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
  93  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
  94  */
  95 int app_context_get_package(app_context_h app_context, char **package) TIZEN_DEPRECATED_API;
  96
  97
  98 /**
  99  * @brief    Gets the application ID with the given application context.
 100  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 101  * @remarks     You must release @a app_id using free().
 102  * @param[in]   app_context  The application context
 103  * @param[out]  app_id       The application ID of the given application context
 104  * @return      @c 0 on success,
 105  *              otherwise a negative error value
 106  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 107  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 108  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 109  */
 110 int app_context_get_app_id(app_context_h app_context, char **app_id);
 111
 112
 113 /**
 114  * @brief  Gets the process ID with the given application context.
 115  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 116  * @param[in]   app_context  The application context
 117  * @param[out]  pid          The process ID of the given application context
 118  * @return      @c 0 on success,
 119  *              otherwise a negative error value
 120  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 121  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 122  */
 123 int app_context_get_pid(app_context_h app_context, pid_t *pid);
 124
 125
 126 /**
 127  * @brief  Gets the package id with the given application context.
 128  * @since_tizen 3.0
 129  * @remarks     You must release @a pkg_id using free().
 130  * @param[in]   app_context  The application context
 131  * @param[out]  pkg_id   The package ID of the given application context
 132  * @return      @c 0 on success,
 133  *              otherwise a negative error value
 134  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 135  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 136  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 137  */
 138 int app_context_get_package_id(app_context_h app_context, char **pkg_id);
 139
 140
 141 /**
 142  * @brief  Gets the application state with the given application context.
 143  * @since_tizen 3.0
 144  * @remarks Note that application's state might be changed after you get app_context.
 145  *          This function just returns the state of application when you get the app_context.
 146  * @param[in]   app_context  The application context
 147  * @param[out]  state        The application state of the given application context
 148  * @return      @c 0 on success,
 149  *              otherwise a negative error value
 150  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 151  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 152  */
 153 int app_context_get_app_state(app_context_h app_context, app_state_e *state);
 154
 155
 156 /**
 157  * @brief  Checks whether the application with the given application context is terminated.
 158  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 159  * @param[in]   app_context  The application context
 160  * @param[out]  terminated   @c true if the application is terminated, \n
 161  *                           otherwise @c false if the application is running
 162  * @return      @c 0 on success,
 163  *              otherwise a negative error value
 164  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 165  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 166  */
 167 int app_context_is_terminated(app_context_h app_context, bool *terminated);
 168
 169
 170 /**
 171  * @brief  Checks whether two application contexts are equal.
 172  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 173  * @param[in]   lhs    The first application context to compare
 174  * @param[in]   rhs    The second application context to compare
 175  * @param[out]  equal  @c true if the application contexts are equal, \n
 176  *                     otherwise @c false if they are not equal
 177  * @return      @c 0 on success,
 178  *              otherwise a negative error value
 179  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 180  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 181  */
 182 int app_context_is_equal(app_context_h lhs, app_context_h rhs, bool *equal);
 183
 184
 185 /**
 186  * @brief  Checks whether the application is running as a sub application of the application group.
 187  * @since_tizen 3.0
 188  * @param[in]   app_context  The application context
 189  * @param[out]  is_sub_app @c true if the sub application of the group, \n
 190  *                    otherwise @c false if the main application of the group
 191  * @return      @c 0 on success,
 192  *              otherwise a negative error value
 193  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 194  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 195  */
 196 int app_context_is_sub_app(app_context_h app_context, bool *is_sub_app);
 197
 198 /**
 199  * @brief  Clones the application context handle.
 200  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 201  * @remarks The @a clone should be released using app_context_destroy()
 202  * @param[out]  clone        The newly created application context handle, if cloning is successful
 203  * @param[in]   app_context  The application context
 204  * @return      @c 0 on success,
 205  *              otherwise a negative error value
 206  * @retval  #APP_MANAGER_ERROR_NONE               Successful
 207  * @retval  #APP_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 208  * @retval  #APP_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 209  */
 210 int app_context_clone(app_context_h *clone, app_context_h app_context);
 211
 212
 213 /**
 214  * @}
 215  */
 216
 217 #ifdef __cplusplus
 218 }
 219 #endif
 220
 221 #endif /* __TIZEN_APPFW_APP_CONTEXT_H */
 222