include/ail.h

   1 /*
   2  * ail
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jayoun Lee <airjany@samsung.com>, Sewook Park <sewook7.park@samsung.com>, Jaeho Lee <jaeho81.lee@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22
  23
  24
  25 #ifndef __AIL_H__
  26 #define __AIL_H__
  27
  28 #include <stdbool.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif /* __cplusplus */
  33
  34
  35
  36 /**
  37  * @open
  38  * @ingroup APPLICATION_FRAMEWORK
  39  * @defgroup ail Application Information Library
  40  */
  41
  42 /**
  43  * @file       ail.h
  44  * @brief      Application Information Library header
  45  * @author     Sunghyuk Lee (sunghyuk.lee@samsung.com), Jin Yoon (jinny.yoon@samsung.com)
  46  * @date       2011-07-30
  47  * @version    0.1
  48  */
  49
  50 /**
  51  * @addtogroup ail
  52  * @{
  53  */
  54
  55 /**
  56  * @brief string type properties
  57  */
  58 #define AIL_PROP_PACKAGE_STR                    "AIL_PROP_PACKAGE_STR"
  59 #define AIL_PROP_EXEC_STR                       "AIL_PROP_EXEC_STR"
  60 #define AIL_PROP_NAME_STR                       "AIL_PROP_NAME_STR"
  61 #define AIL_PROP_TYPE_STR                       "AIL_PROP_TYPE_STR"
  62 #define AIL_PROP_ICON_STR                       "AIL_PROP_ICON_STR"
  63 #define AIL_PROP_CATEGORIES_STR                 "AIL_PROP_CATEGORIES_STR"
  64 #define AIL_PROP_VERSION_STR                    "AIL_PROP_VERSION_STR"
  65 #define AIL_PROP_MIMETYPE_STR                   "AIL_PROP_MIMETYPE_STR"
  66 #define AIL_PROP_X_SLP_SERVICE_STR              "AIL_PROP_X_SLP_SERVICE_STR"
  67 #define AIL_PROP_X_SLP_PACKAGETYPE_STR          "AIL_PROP_X_SLP_PACKAGETYPE_STR"
  68 #define AIL_PROP_X_SLP_PACKAGECATEGORIES_STR    "AIL_PROP_X_SLP_PACKAGECATEGORIES_STR"
  69 #define AIL_PROP_X_SLP_PACKAGEID_STR            "AIL_PROP_X_SLP_PACKAGEID_STR"
  70 #define AIL_PROP_X_SLP_SVC_STR                  "AIL_PROP_X_SLP_SVC_STR"
  71 #define AIL_PROP_X_SLP_EXE_PATH                 "AIL_PROP_X_SLP_EXE_PATH"
  72 #define AIL_PROP_X_SLP_APPID_STR                "AIL_PROP_X_SLP_APPID_STR"
  73 #define AIL_PROP_X_SLP_PKGID_STR                "AIL_PROP_X_SLP_PKGID_STR"
  74 #define AIL_PROP_X_SLP_DOMAIN_STR               "AIL_PROP_X_SLP_DOMAIN_STR"
  75
  76
  77 /**
  78  * @brief integer type properties
  79  */
  80 #define AIL_PROP_X_SLP_TEMP_INT                 "AIL_PROP_X_SLP_TEMP_INT"
  81 #define AIL_PROP_X_SLP_INSTALLEDTIME_INT        "AIL_PROP_X_SLP_INSTALLEDTIME_INT"
  82
  83 /**
  84  * @brief boolean type properties
  85  */
  86 #define AIL_PROP_NODISPLAY_BOOL                 "AIL_PROP_NODISPLAY_BOOL"
  87 #define AIL_PROP_X_SLP_TASKMANAGE_BOOL          "AIL_PROP_X_SLP_TASKMANAGE_BOOL"
  88 #define AIL_PROP_X_SLP_MULTIPLE_BOOL            "AIL_PROP_X_SLP_MULTIPLE_BOOL"
  89 #define AIL_PROP_X_SLP_REMOVABLE_BOOL           "AIL_PROP_X_SLP_REMOVABLE_BOOL"
  90 #define AIL_PROP_X_SLP_INACTIVATED_BOOL         "AIL_PROP_X_SLP_INACTIVATED_BOOL"
  91
  92
  93 /**
  94  * @brief A handle for filters
  95  */
  96 typedef struct ail_filter *ail_filter_h;
  97
  98 /**
  99  * @brief A handle for appinfos
 100  */
 101 typedef struct ail_appinfo *ail_appinfo_h;
 102
 103 /**
 104  * @brief return values
 105  */
 106 typedef enum {
 107         AIL_ERROR_OK = 0,                                               /**< General success */
 108         AIL_ERROR_FAIL = -1,                                    /**< General error */
 109         AIL_ERROR_DB_FAILED = -2,                               /**< Database error */
 110         AIL_ERROR_OUT_OF_MEMORY = -3,                   /**< Out of memory */
 111         AIL_ERROR_INVALID_PARAMETER = -4,               /**< Invalid parameter */
 112         AIL_ERROR_NO_DATA = -5,                                 /**< Success, but no data */
 113 } ail_error_e;
 114
 115 /**
 116  * @fn ail_error_e ail_filter_new(ail_filter_h *filter)
 117  *
 118  * @brief  Create a new filter handle which is used to filter records from Application Information Database. You can add filtering conditions to filter with ail_filter_add_xxx functions. All conditions are ANDed.
 119  *
 120  * @par Sync (or) Async : Synchronous API.
 121  *
 122  * @param[out] filter a pointer to a filter which is newly created
 123  *
 124  * @return 0 if success, negative value(<0) if fail\n
 125  * @retval      AIL_ERROR_OK                                    success
 126  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 127  * @retval      AIL_ERROR_OUT_OF_MEMORY                 out of memory
 128  *
 129  * @pre None
 130  * @post If the filter is no longer used, it should be freed with ail_filter_destroy()
 131  *
 132  * @see  ail_filter_destroy()
 133  *
 134  * @par Prospective Clients:
 135  * External Apps.
 136  *
 137  * @code
 138 int count_apps()
 139 {
 140         ail_filter_h filter;
 141         ail_error_e ret;
 142         int n;
 143
 144         ret = ail_filter_new(&filter);
 145         if (ret != AIL_ERROR_OK) {
 146                 return -1;
 147         }
 148
 149         ret = ail_filter_add_bool(filter, AIL_PROP_NODISPLAY_BOOL, false);
 150         if (ret != AIL_ERROR_OK) {
 151                 return -1;
 152         }
 153
 154         ret = ail_filter_add_str(filter, AIL_PROP_MIMETYPE_STR, "audio/wav");
 155         if (ret != AIL_ERROR_OK) {
 156                 return -1;
 157         }
 158
 159         ret = ail_filter_count_appinfo(filter, &n);
 160         if (ret != AIL_ERROR_OK) {
 161                 return -1;
 162         }
 163         ret = ail_filter_destroy(filter);
 164
 165         printf("N of apps not to be displayed and supporting 'audo/wav' mime type = %d\n", n);
 166
 167         return n;
 168 }
 169  * @endcode
 170  */
 171 ail_error_e ail_filter_new(ail_filter_h *filter);
 172
 173
 174
 175 /**
 176  * @fn ail_error_e ail_error_e ail_filter_add_int(ail_filter_h filter, const char *property, const int value)
 177  *
 178  * @brief Add integer condition to filter
 179  *
 180  * @par Sync (or) Async : Synchronous API
 181  *
 182  * @param[in] filter    a filter handle which can be create with ail_filter_new()
 183  * @param[in] property          a property type of integer
 184  * @param[in] value             the value to filter by
 185  *
 186  * @return 0 if success, negative value(<0) if fail\n
 187  * @retval      AIL_ERROR_OK                                    success
 188  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 189  * @retval      AIL_ERROR_OUT_OF_MEMORY                 out of memory
 190  *
 191  * @pre The filter should be valid handle which was created by ail_filter_new()
 192  *
 193  * @see  ail_filter_new()
 194  *
 195  * @par Prospective Clients:
 196  * External Apps.
 197  *
 198  * @code
 199 int count_apps()
 200 {
 201         ail_filter_h filter;
 202         ail_error_e ret;
 203         int n;
 204
 205         ret = ail_filter_new(&filter);
 206         if (ret != AIL_ERROR_OK) {
 207                 return -1;
 208         }
 209
 210         ret = ail_filter_add_int(filter, AIL_PROP_X_SLP_BASELAYOUTWIDTH_INT, 480);
 211         if (ret != AIL_ERROR_OK) {
 212                 return -1;
 213         }
 214
 215         ret = ail_filter_count_appinfo(filter, &n);
 216         if (ret != AIL_ERROR_OK) {
 217                 return -1;
 218         }
 219
 220         printf("N of apps = %d\n", n);
 221
 222         return n;
 223 }
 224  * @endcode
 225  */
 226 ail_error_e ail_filter_add_int(ail_filter_h filter, const char *property, const int value);
 227
 228
 229 /**
 230  * @fn ail_error_e ail_error_e ail_filter_add_bool(ail_filter_h filter, const char *property, const bool value)
 231  *
 232  * @brief Add boolean condition to filter by. The value can be true/false only
 233  *
 234  * @par Sync (or) Async : Synchronous API
 235  *
 236  * @param[in] filter     a filter handle which can be create with ail_filter_new()
 237  * @param[in] property   a property type of boolean
 238  * @param[in] value      the value to filter by
 239  *
 240  * @return 0 if success, negative value(<0) if fail\n
 241  * @retval      AIL_ERROR_OK                                    success
 242  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 243  * @retval      AIL_ERROR_OUT_OF_MEMORY                 out of memory
 244  *
 245  * @pre The filter should be valid handle which was created by ail_filter_new()
 246  *
 247  * @see  ail_filter_new()
 248  *
 249  * @par Prospective Clients:
 250  * External Apps.
 251  *
 252  * @code
 253 int count_apps()
 254 {
 255         ail_filter_h filter;
 256         ail_error_e ret;
 257         int n;
 258
 259         ret = ail_filter_new(&filter);
 260         if (ret != AIL_ERROR_OK) {
 261                 return -1;
 262         }
 263
 264         ret = ail_filter_add_bool(filter, AIL_PROP_X_SLP_REMOVABLE_BOOL, true);
 265         if (ret != AIL_ERROR_OK) {
 266                 return -1;
 267         }
 268
 269         ret = ail_filter_count_appinfo(filter, &n);
 270         if (ret != AIL_ERROR_OK) {
 271                 return -1;
 272         }
 273
 274         fprintf(stderr, "N of apps = %d\n", n);
 275
 276         return n;
 277 }
 278  * @endcode
 279  */
 280 ail_error_e ail_filter_add_bool(ail_filter_h filter, const char *property, bool value);
 281
 282
 283
 284 /**
 285  * @fn ail_error_e ail_error_e ail_filter_add_str(ail_filter_h filter, const char *property, const char *value)
 286  *
 287  * @brief Add string condition to filter by. The string is case-sensitive.
 288  *
 289  * @par Sync (or) Async : Synchronous API
 290  *
 291  * @param[in] filter     a filter handle which can be create with ail_filter_new()
 292  * @param[in] property   a property type of string
 293  * @param[in] value      the value to filter by
 294  *
 295  * @return 0 if success, negative value(<0) if fail\n
 296  * @retval      AIL_ERROR_OK                                    success
 297  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 298  * @retval      AIL_ERROR_OUT_OF_MEMORY                 out of memory
 299  *
 300  * @pre The filter should be valid handle which was created by ail_filter_new()
 301  *
 302  * @see  ail_filter_new()
 303  *
 304  * @par Prospective Clients:
 305  * External Apps.
 306  *
 307  * @code
 308 int count_apps()
 309 {
 310         ail_filter_h filter;
 311         ail_error_e ret;
 312         int n;
 313
 314         ret = ail_filter_new(&filter);
 315         if (ret != AIL_ERROR_OK) {
 316                 return -1;
 317         }
 318
 319         ret = ail_filter_add_str(filter, AIL_PROP_PACKAGE_STR, "com.samsung.memo");
 320         if (ret != AIL_ERROR_OK) {
 321                 return -1;
 322         }
 323
 324         ret = ail_filter_count_appinfo(filter, &n);
 325         if (ret != AIL_ERROR_OK) {
 326                 return -1;
 327         }
 328
 329         fprintf(stderr, "N of apps = %d\n", n);
 330
 331         return n;
 332 }
 333  * @endcode
 334  */
 335 ail_error_e ail_filter_add_str(ail_filter_h filter, const char *property, const char *value);
 336
 337
 338
 339 /**
 340  * @fn ail_error_e ail_filter_destroy(ail_filter_h filter)
 341  *
 342  * @brief Destroy a filter which is not used any longer.
 343  *
 344  * @par Sync (or) Async : Synchronous API
 345  *
 346  * @param[in] filter    filter handle
 347  *
 348  * @return 0 if success, negative value(<0) if fail\n
 349  * @retval      AIL_ERROR_OK    success
 350  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 351  *
 352  * @post If the filter is no longer used, it should be freed with ail_filter_destroy()
 353  *
 354  * @see  ail_filter_new()
 355  *
 356  * @par Prospective Clients:
 357  * External Apps.
 358  *
 359  * @code
 360 int count_apps()
 361 {
 362         ail_filter_h filter;
 363         ail_error_e ret;
 364         int n;
 365
 366         ret = ail_filter_new(&filter);
 367         if (ret != AIL_ERROR_OK) {
 368                 return -1;
 369         }
 370
 371         ret = ail_filter_add_bool(filter, AIL_PROP_X_SLP_REMOVABLE_BOOL, true);
 372         if (ret != AIL_ERROR_OK) {
 373                 return -1;
 374         }
 375
 376         ret = ail_filter_count_appinfo(filter, &n);
 377         if (ret != AIL_ERROR_OK) {
 378                 return -1;
 379         }
 380
 381         printf("N of removable apps = %d\n", n);
 382
 383         ret = ail_filter_add_str(filter, AIL_PROP_MIMETYPE_STR, "audio/wav");
 384         if (ret != AIL_ERROR_OK) {
 385                 return -1;
 386         }
 387
 388         ret = ail_filter_count_appinfo(filter, &n);
 389         if (ret != AIL_ERROR_OK) {
 390                 return -1;
 391         }
 392
 393         printf("N of apps removable and supporting 'audo/wav' mime type = %d\n", n);
 394
 395         ret = ail_filter_destroy(filter);
 396
 397         return n;
 398 }
 399  * @endcode
 400  */
 401 ail_error_e ail_filter_destroy(ail_filter_h filter);
 402
 403
 404
 405 /**
 406  * @brief return value type of ail_list_appinfo_cb
 407  */
 408 typedef enum {
 409         AIL_CB_RET_CONTINUE = 1,                /**< continue */
 410         AIL_CB_RET_CANCEL = 0,                  /**< cancel */
 411 } ail_cb_ret_e;
 412
 413 /**
 414  * @fn ail_cb_ret_e (*ail_list_appinfo_cb) (const ail_appinfo_h appinfo_h, void *user_data)
 415  *
 416  * @breif Specifies the type of functions passed to ail_filter_list_appinfo_foreach().
 417  *
 418  * @param[in] appinfo_h the appinfo's handle
 419  * @param[in] user_data user data passed to ail_filtet_list_appinfo_foreach()
 420  *
 421  * @return 0 if success, negative value(<0) if fail\n
 422  * @retval      AIL_CB_RET_CONTINUE                             return if you continue iteration
 423  * @retval      AIL_CB_RET_CANCEL                               return if you cancel iteration
 424  *
 425  * @see  ail_filter_list_appinfo_foreach()
 426  */
 427 typedef ail_cb_ret_e (*ail_list_appinfo_cb) (const ail_appinfo_h appinfo_h, void *user_data);
 428
 429 /**
 430  * @fn ail_error_e ail_error_e ail_filter_list_appinfo_foreach(ail_filter_h filter, ail_list_appinfo_cb func, void *user_data)
 431  *
 432  * @brief Calls the callback function for each app filtered by given filter. If the filter is not given (i.e filter handle is NULL), it is invoked for all apps.
 433  *
 434  * @par Sync (or) Async : Synchronous API
 435  *
 436  * @param[in] filter            a filter handle
 437  * @param[in] func                      the function to call with each app's appinfo
 438  * @param[in] user_data         user_data to pass to the function
 439  *
 440  * @return  0 if success, negative value(<0) if fail\n
 441  * @retval AIL_ERROR_OK                                 success
 442  * @retval AIL_ERROR_DB_FAILED                          database error
 443  * @retval AIL_ERROR_INVALID_PARAMETER          invalid parameter
 444  *
 445  * @see  ail_list_appinfo_cb
 446  * @see ail_filter_add_bool()
 447  * @see ail_filter_add_int()
 448  * @see ail_filter_add_str()
 449  *
 450  * @par Prospective Clients:
 451  * External Apps.
 452  *
 453  * @code
 454
 455 ail_cb_ret_e appinfo_func(const ail_appinfo_h appinfo, void *user_data)
 456 {
 457         int *i = (int *)user_data;
 458         char *appid;
 459
 460         ail_appinfo_get_str(appinfo, AIL_PROP_PACKAGE_STR, &appid);
 461         printf("i=%d %s\n", (*i)++, appid);
 462
 463         if (*i > 30)
 464                 return AIL_CB_RET_CANCEL;
 465
 466         return AIL_CB_RET_CONTINUE;
 467 }
 468
 469 int list_apps()
 470 {
 471         ail_filter_h filter;
 472         ail_error_e ret;
 473         int i=0;
 474
 475         ret = ail_filter_new(&filter);
 476         if (ret != AIL_ERROR_OK) {
 477                 return -1;
 478         }
 479
 480         ret = ail_filter_add_bool(filter, AIL_PROP_X_SLP_REMOVABLE_BOOL, true);
 481         if (ret != AIL_ERROR_OK) {
 482                 return -1;
 483         }
 484
 485         ret = ail_filter_add_str(filter, AIL_PROP_TYPE_STR, "Application");
 486         if (ret != AIL_ERROR_OK) {
 487                 return -1;
 488         }
 489
 490         printf("List apps which are removable and 'Application' typed\n");
 491         ail_filter_list_appinfo_foreach(filter, appinfo_func, (void *)&i);
 492
 493         ail_filter_destroy(filter);
 494
 495         return 0;
 496 }
 497  * @endcode
 498  */
 499 ail_error_e ail_filter_list_appinfo_foreach(ail_filter_h filter,
 500                                             ail_list_appinfo_cb appinfo_func,
 501                                             void *user_data);
 502
 503
 504
 505 /**
 506  * @fn ail_error_e ail_error_e ail_filter_count_appinfo(ail_filter_h filter, int *count)
 507  *
 508  * @brief Gets the number of app which is filtered by the given filter. If the filter is not given (i.e filter handle is NULL), all app are counted.
 509  *
 510  * @par Sync (or) Async : Synchronous API
 511  *
 512  * @param[in] filter    a filter handle
 513  * @param[in] count             the number of appinfo which is filtered
 514  *
 515  * @return 0 if success, negative value(<0) if fail\n
 516  * @retval      AIL_ERROR_OK                                    success
 517  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 518  * @retval      AIL_ERROR_OUT_OF_MEMORY                 out of memory
 519  *
 520  * @pre None
 521  * @post None
 522  *
 523  * @see ail_filter_new()
 524  * @see ail_filter_add_bool()
 525  * @see ail_filter_add_int()
 526  * @see ail_filter_add_str()
 527  *
 528  * @par Prospective Clients:
 529  * External Apps.
 530  *
 531  * @code
 532 int count_apps()
 533 {
 534         ail_filter_h filter;
 535         ail_error_e ret;
 536         int n;
 537
 538         ret = ail_filter_new(&filter);
 539         if (ret != AIL_ERROR_OK) {
 540                 return -1;
 541         }
 542
 543         ret = ail_filter_add_bool(filter, AIL_PROP_NODISPLAY_BOOL, true);
 544         if (ret != AIL_ERROR_OK) {
 545                 return -1;
 546         }
 547
 548         ret = ail_filter_count_appinfo(filter, &n);
 549         if (ret != AIL_ERROR_OK) {
 550                 return -1;
 551         }
 552
 553         printf("N of app not to be displayed = %d", n);
 554
 555         ret = ail_filter_count_appinfo(NULL, &n);
 556         if (ret != AIL_ERROR_OK) {
 557                 return -1;
 558         }
 559
 560         printf("N of all app = %d\n", n);
 561
 562         return n;
 563 }
 564  * @endcode
 565  */
 566 ail_error_e ail_filter_count_appinfo(ail_filter_h filter, int *count);
 567
 568
 569
 570 /**
 571  * @fn ail_error_e ail_package_get_appinfo(const char *package, ail_appinfo_h *handle)
 572  *
 573  * @brief get an application information related to a package.
 574         This API just retrieves all the information of the package from Application Information Database.
 575         All data related to the package are loaded in the memory after calling this function.
 576         If you want to read a value from the retrieving data, you have to use the functions of ail_appinfo_get_xxx.
 577
 578  * @par Sync (or) Async : Synchronous API.
 579  *
 580  * @param[in] package package name what you want to know about.
 581  * @param[out] handle handle will be used with the functions of ail_appinfo_get_xxx. If no data, it will be NULL.
 582  *
 583  * @return 0 if success, negative value(<0) if fail\n
 584  * @retval      AIL_ERROR_OK                                    success
 585  * @retval      AIL_ERROR_FAIL                                  internal error
 586  * @retval      AIL_ERROR_DB_FAILED                             database error
 587  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 588  * @retval      AIL_ERROR_NO_DATA                               no data. cannot find the package.
 589  *
 590  * @pre declare a handle before calling this function. The handle is used as a second argument of this API.
 591  * @post destroy the handle with the function of ail_package_destroy_appinfo after using it all.
 592  *
 593  * @see  ail_package_destroy_appinfo(), ail_appinfo_get_bool(), ail_appinfo_get_int(), ail_appinfo_get_str()
 594  *
 595  * @par Prospective Clients:
 596  * External Apps.
 597  *
 598  * @code
 599 static ail_error_e _get_name(const char *package)
 600 {
 601         ail_appinfo_h handle;
 602         ail_error_e ret;
 603         char *str;
 604
 605         ret = ail_package_get_appinfo(package, &handle);
 606         if (ret != AIL_ERROR_OK) {
 607                 return AIL_ERROR_FAIL;
 608         }
 609
 610         ret = ail_appinfo_get_str(handle, AIL_PROP_NAME_STR, &str);
 611         if (ret != AIL_ERROR_OK) {
 612                 return AIL_ERROR_FAIL;
 613         }
 614         fprintf(stderr, "Package[%s], Property[%s] : %s\n", package, property, str);
 615
 616         ret = ail_package_destroy_appinfo(handle);
 617         if (ret != AIL_ERROR_OK) {
 618                 return AIL_ERROR_FAIL;
 619         }
 620
 621         return AIL_ERROR_OK;
 622 }
 623  * @endcode
 624  */
 625 ail_error_e ail_package_get_appinfo(const char *package, ail_appinfo_h *handle) __attribute__((deprecated));
 626
 627
 628 /**
 629  * @fn ail_error_e ail_get_appinfo(const char *appid, ail_appinfo_h *handle)
 630  *
 631  * @brief get an application information related to a appid.
 632         This API just retrieves all the information of the application from Application Information Database.
 633         All data related to the appid are loaded in the memory after calling this function.
 634         If you want to read a value from the retrieving data, you have to use the functions of ail_appinfo_get_xxx.
 635
 636  * @par Sync (or) Async : Synchronous API.
 637  *
 638  * @param[in] appid appid what you want to know about.
 639  * @param[out] handle handle will be used with the functions of ail_appinfo_get_xxx. If no data, it will be NULL.
 640  *
 641  * @return 0 if success, negative value(<0) if fail\n
 642  * @retval      AIL_ERROR_OK                                    success
 643  * @retval      AIL_ERROR_FAIL                                  internal error
 644  * @retval      AIL_ERROR_DB_FAILED                             database error
 645  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 646  * @retval      AIL_ERROR_NO_DATA                               no data. cannot find the app.
 647  *
 648  * @pre declare a handle before calling this function. The handle is used as a second argument of this API.
 649  * @post destroy the handle with the function of ail_get_appinfo after using it all.
 650  *
 651  * @see  ail_get_appinfo(), ail_appinfo_get_bool(), ail_appinfo_get_int(), ail_appinfo_get_str()
 652  *
 653  * @par Prospective Clients:
 654  * External Apps.
 655  *
 656  * @code
 657 static ail_error_e _get_name(const char *appid)
 658 {
 659         ail_appinfo_h handle;
 660         ail_error_e ret;
 661         char *str;
 662
 663         ret = ail_get_appinfo(appid, &handle);
 664         if (ret != AIL_ERROR_OK) {
 665                 return AIL_ERROR_FAIL;
 666         }
 667
 668         ret = ail_appinfo_get_str(handle, AIL_PROP_NAME_STR, &str);
 669         if (ret != AIL_ERROR_OK) {
 670                 return AIL_ERROR_FAIL;
 671         }
 672         fprintf(stderr, "Package[%s], Property[%s] : %s\n", appid, property, str);
 673
 674         ret = ail_destroy_appinfo(handle);
 675         if (ret != AIL_ERROR_OK) {
 676                 return AIL_ERROR_FAIL;
 677         }
 678
 679         return AIL_ERROR_OK;
 680 }
 681  * @endcode
 682  */
 683 ail_error_e ail_get_appinfo(const char *appid, ail_appinfo_h *handle);
 684
 685
 686 /**
 687  * @fn ail_error_e ail_appinfo_get_bool(const ail_appinfo_h handle, const char *property, bool *value)
 688  *
 689  * @brief get a boolean value related to the property.
 690         Before using this API, the handle is defined by calling ail_get_appinfo.
 691         This function needs a out-parameter for the value.
 692  *
 693  * @par Sync (or) Async : Synchronous API.
 694  *
 695  * @param[in] handle    the handle is defined by calling ail_get_appinfo.
 696  * @param[in] property   a property type of boolean
 697  * @param[out] value    a out-parameter value that is mapped with the property.
 698  *
 699  * @return 0 if success, negative value(<0) if fail\n
 700  * @retval      AIL_ERROR_OK                                    success
 701  * @retval      AIL_ERROR_DB_FAILED                             database error
 702  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 703  *
 704  * @pre define a handle using ail_get_appinfo. The handle is used as a first argument of this API.
 705  * @post destroy the handle with the function of ail_destroy_appinfo after using it all.
 706  *
 707  * @see  ail_get_appinfo(), ail_destroy_appinfo(), ail_appinfo_get_int(), ail_appinfo_get_str()
 708  *
 709  * @par Prospective Clients:
 710  * External Apps.
 711  *
 712  * @code
 713 static ail_error_e _get_nodisplay(const char *appid)
 714 {
 715         ail_appinfo_h handle;
 716         ail_error_e ret;
 717         bool value;
 718
 719         ret = ail_get_appinfo(appid, &handle);
 720         if (ret != AIL_ERROR_OK) {
 721                 return AIL_ERROR_FAIL;
 722         }
 723
 724         ret = ail_appinfo_get_bool(handle, AIL_PROP_NODISPLAY_BOOL, &value);
 725         if (ret != AIL_ERROR_OK) {
 726                 return AIL_ERROR_FAIL;
 727         }
 728         fprintf(stderr, "appid[%s] : %d\n", appid, value);
 729
 730         ret = ail_destroy_appinfo(handle);
 731         if (ret != AIL_ERROR_OK) {
 732                 return AIL_ERROR_FAIL;
 733         }
 734
 735         return AIL_ERROR_OK;
 736 }
 737  * @endcode
 738  */
 739 ail_error_e ail_appinfo_get_bool(const ail_appinfo_h handle, const char *property, bool *value);
 740
 741
 742
 743 /**
 744  * @fn ail_error_e ail_appinfo_get_int(const ail_appinfo_h handle, const char *property, int *value)
 745  *
 746  * @brief get a integer value related to the property.
 747         Before using this API, the handle is defined by calling ail_get_appinfo.
 748         This function needs a out-parameter for the value.
 749  *
 750  * @par Sync (or) Async : Synchronous API.
 751  *
 752  * @param[in] handle    the handle is defined by calling ail_get_appinfo.
 753  * @param[in] property  a property type of integer.
 754  * @param[out] value    a out-parameter value that is mapped with the property.
 755  *
 756  * @return 0 if success, negative value(<0) if fail\n
 757  * @retval      AIL_ERROR_OK                                    success
 758  * @retval      AIL_ERROR_DB_FAILED                             database error
 759  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 760  *
 761  * @pre define a handle using ail_get_appinfo. The handle is used as a first argument of this API.
 762  * @post destroy the handle with the function of ail_destroy_appinfo after using it all.
 763  *
 764  * @see  ail_get_appinfo(), ail_destroy_appinfo(), ail_appinfo_get_bool(), ail_appinfo_get_str()
 765  *
 766  * @par Prospective Clients:
 767  * External Apps.
 768  *
 769  * @code
 770 static ail_error_e _get_x_slp_baselayoutwidth(const char *appid)
 771 {
 772         ail_appinfo_h handle;
 773         ail_error_e ret;
 774         int value;
 775
 776         ret = ail_get_appinfo(appid, &handle);
 777         if (ret != AIL_ERROR_OK) {
 778                 return AIL_ERROR_FAIL;
 779         }
 780
 781         ret = ail_appinfo_get_int(handle, AIL_PROP_X_SLP_BASELAYOUTWIDTH_INT, &value);
 782         if (ret != AIL_ERROR_OK) {
 783                 return AIL_ERROR_FAIL;
 784         }
 785         fprintf(stderr, "Package[%s] : %d\n", appid, value);
 786
 787         ret = ail_destroy_appinfo(handle);
 788         if (ret != AIL_ERROR_OK) {
 789                 return AIL_ERROR_FAIL;
 790         }
 791
 792         return AIL_ERROR_OK;
 793 }
 794  * @endcode
 795  */
 796 ail_error_e ail_appinfo_get_int(const ail_appinfo_h handle, const char *property, int *value);
 797
 798
 799
 800 /**
 801  * @fn ail_error_e ail_appinfo_get_str(const ail_appinfo_h handle, const char *property, char **str)
 802  *
 803  * @brief get a string related to the property.
 804         Before using this API, the handle is defined by calling ail_get_appinfo.
 805         This function needs a out-parameter for the value.
 806  *
 807  * @par Sync (or) Async : Synchronous API.
 808  *
 809  * @param[in] handle    the handle is defined by calling ail_get_appinfo.
 810  * @param[in] property  a property type of string.
 811  * @param[out] str              a out-parameter string that is mapped with the property. The icon property contains the absolute file path. If there is no data, the value of str is NULL.
 812  *
 813  * @return 0 if success, negative value(<0) if fail\n
 814  * @retval      AIL_ERROR_OK                                    success
 815  * @retval      AIL_ERROR_DB_FAILED                             database error
 816  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 817  *
 818  * @pre define a handle using ail_get_appinfo. The handle is used as a first argument of this API.
 819  * @post str doesn't need to be freed. It will be freed by calling ail_destroy_appinfo.
 820  *
 821  * @see  ail_get_appinfo(), ail_destroy_appinfo(), ail_appinfo_get_bool(), ail_appinfo_get_int()
 822  *
 823  * @par Prospective Clients:
 824  * External Apps.
 825  *
 826  * @code
 827 static ail_error_e _get_nodisplay(const char *appid)
 828 {
 829         ail_appinfo_h handle;
 830         ail_error_e ret;
 831         char* value;
 832
 833         ret = ail_get_appinfo(appid, &handle);
 834         if (ret != AIL_ERROR_OK) {
 835                 return AIL_ERROR_FAIL;
 836         }
 837
 838         ret = ail_appinfo_get_str(handle, AIL_PROP_NAME_STR, &value);
 839         if (ret != AIL_ERROR_OK) {
 840                 return AIL_ERROR_FAIL;
 841         }
 842         fprintf(stderr, "Package[%s] : %d\n", appid, value);
 843
 844         ret = ail_destroy_appinfo(handle);
 845         if (ret != AIL_ERROR_OK) {
 846                 return AIL_ERROR_FAIL;
 847         }
 848
 849         return AIL_ERROR_OK;
 850 }
 851  * @endcode
 852  */
 853 ail_error_e ail_appinfo_get_str(const ail_appinfo_h handle, const char *property, char **str);
 854
 855
 856
 857 /**
 858  * @fn ail_error_e ail_package_destroy_appinfo(const ail_appinfo_h handle)
 859  *
 860  * @brief destroy a handle what you get with the function of ail_package_get_appinfo.
 861  *
 862  * @par Sync (or) Async : Synchronous API.
 863  *
 864  * @param[in] handle destroy all resources related to the handle.
 865  *
 866  * @return 0 if success, negative value(<0) if fail\n
 867  * @retval      AIL_ERROR_OK                                    success
 868  * @retval      AIL_ERROR_DB_FAILED                             database error
 869  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 870  *
 871  * @pre need a handle that you don't need anymore.
 872  * @post cannot use the handle after destroying.
 873  *
 874  * @see  ail_package_get_appinfo(), ail_appinfo_get_bool(), ail_appinfo_get_int(), ail_appinfo_get_str()
 875  *
 876  * @par Prospective Clients:
 877  * External Apps.
 878  *
 879  * @code
 880 static ail_error_e _get_name(const char *package)
 881 {
 882         ail_appinfo_h handle;
 883         ail_error_e ret;
 884         char *str;
 885
 886         ret = ail_package_get_appinfo(package, &handle);
 887         if (ret != AIL_ERROR_OK) {
 888                 return AIL_ERROR_FAIL;
 889         }
 890
 891         ret = ail_appinfo_get_str(handle, AIL_PROP_NAME_STR, &str);
 892         if (ret != AIL_ERROR_OK) {
 893                 return AIL_ERROR_FAIL;
 894         }
 895         fprintf(stderr, "Package[%s], Property[%s] : %s\n", package, property, str);
 896
 897         ret = ail_package_destroy_appinfo(handle);
 898         if (ret != AIL_ERROR_OK) {
 899                 return AIL_ERROR_FAIL;
 900         }
 901
 902         return AIL_ERROR_OK;
 903 }
 904  * @endcode
 905  */
 906 ail_error_e ail_package_destroy_appinfo(const ail_appinfo_h handle) __attribute__((deprecated));
 907
 908
 909 /**
 910  * @fn ail_error_e ail_destroy_appinfo(const ail_appinfo_h handle)
 911  *
 912  * @brief destroy a handle what you get with the function of ail_get_appinfo.
 913  *
 914  * @par Sync (or) Async : Synchronous API.
 915  *
 916  * @param[in] handle destroy all resources related to the handle.
 917  *
 918  * @return 0 if success, negative value(<0) if fail\n
 919  * @retval      AIL_ERROR_OK                                    success
 920  * @retval      AIL_ERROR_DB_FAILED                             database error
 921  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 922  *
 923  * @pre need a handle that you don't need anymore.
 924  * @post cannot use the handle after destroying.
 925  *
 926  * @see  ail_get_appinfo(), ail_appinfo_get_bool(), ail_appinfo_get_int(), ail_appinfo_get_str()
 927  *
 928  * @par Prospective Clients:
 929  * External Apps.
 930  *
 931  * @code
 932 static ail_error_e _get_name(const char *appid)
 933 {
 934         ail_appinfo_h handle;
 935         ail_error_e ret;
 936         char *str;
 937
 938         ret = ail_get_appinfo(appid, &handle);
 939         if (ret != AIL_ERROR_OK) {
 940                 return AIL_ERROR_FAIL;
 941         }
 942
 943         ret = ail_appinfo_get_str(handle, AIL_PROP_NAME_STR, &str);
 944         if (ret != AIL_ERROR_OK) {
 945                 return AIL_ERROR_FAIL;
 946         }
 947         fprintf(stderr, "Package[%s], Property[%s] : %s\n", appid, property, str);
 948
 949         ret = ail_destroy_appinfo(handle);
 950         if (ret != AIL_ERROR_OK) {
 951                 return AIL_ERROR_FAIL;
 952         }
 953
 954         return AIL_ERROR_OK;
 955 }
 956  * @endcode
 957  */
 958 ail_error_e ail_destroy_appinfo(const ail_appinfo_h handle);
 959
 960
 961 /**
 962  * @fn ail_error_e ail_desktop_add(const char *appid)
 963  *
 964  * @brief add a app information into Application Information Database.
 965         A desktop file for this app has to be installed in the desktop directory before using this API.
 966         If there is no database for Application Information Database, this API will create the DB.
 967         If there is a DB, this function adds information for the app into the DB.
 968         And a notification is published to the applications who want to know about changing DB.
 969  *
 970  * @par Sync (or) Async : Synchronous API.
 971  *
 972  * @param[in] appid
 973  *
 974  * @return 0 if success, negative value(<0) if fail\n
 975  * @retval      AIL_ERROR_OK                                    success
 976  * @retval      AIL_ERROR_FAIL                                  internal error
 977  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
 978  *
 979  * @pre a desktop file for the app has to be installed in the desktop directory before using this API.
 980  * @post app information is added into the Application Information Database.
 981  *
 982  * @see  ail_desktop_update(), ail_desktop_remove()
 983  *
 984  * @par Prospective Clients:
 985  * External Apps.
 986  *
 987  * @code
 988 static ail_error_e _add_desktop(const char *appid)
 989 {
 990         ail_error_e ret;
 991
 992         if (!appid) {
 993                 return AIL_ERROR_FAIL;
 994         }
 995
 996         ret = ail_desktop_add(appid);
 997         if (ret != AIL_ERROR_OK) {
 998                 return AIL_ERROR_FAIL;
 999         }
1000
1001         return AIL_ERROR_OK;
1002 }
1003  * @endcode
1004  */
1005 ail_error_e ail_desktop_add(const char *appid);
1006
1007
1008
1009 /**
1010  * @fn ail_error_e ail_desktop_update(const char *appid)
1011  *
1012  * @brief update a app information in the Application Information Database.
1013         A desktop file for this app has to be installed in the desktop directory before using this API.
1014         And a notification is published to the applications who want to know about changing DB.
1015  *
1016  * @par Sync (or) Async : Synchronous API.
1017  *
1018  * @param[in] appid
1019  *
1020  * @return 0 if success, negative value(<0) if fail\n
1021  * @retval      AIL_ERROR_OK                                    success
1022  * @retval      AIL_ERROR_FAIL                                  internal error
1023  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
1024  *
1025  * @pre a desktop file for the app has to be installed in the desktop directory before using this API.
1026  * @post update a app information in the Application Information Database.
1027  *
1028  * @see  ail_desktop_add(), ail_desktop_remove()
1029  *
1030  * @par Prospective Clients:
1031  * External Apps.
1032  *
1033  * @code
1034 static ail_error_e _update_desktop(const char *appid)
1035 {
1036         ail_error_e ret;
1037
1038         if (!appid) {
1039                 return AIL_ERROR_FAIL;
1040         }
1041
1042         ret = ail_desktop_update(appid);
1043         if (ret != AIL_ERROR_OK) {
1044                 return AIL_ERROR_FAIL;
1045         }
1046
1047         return AIL_ERROR_OK;
1048 }
1049  * @endcode
1050  */
1051 ail_error_e ail_desktop_update(const char *appid);
1052
1053
1054
1055 /**
1056  * @fn ail_error_e ail_desktop_remove(const char *appid)
1057  *
1058  * @brief remove a app information in the Application Information Database.
1059         And a notification is published to the applications who want to know about changing DB.
1060  *
1061  * @par Sync (or) Async : Synchronous API.
1062  *
1063  * @param[in] appid
1064  *
1065  * @return 0 if success, negative value(<0) if fail\n
1066  * @retval      AIL_ERROR_OK                                    success
1067  * @retval      AIL_ERROR_FAIL                                  internal error
1068  * @retval      AIL_ERROR_INVALID_PARAMETER             invalid parameter
1069  *
1070  * @pre no pre-condition.
1071  * @post app information is removed in the Application Information Database.
1072  *
1073  * @see  ail_desktop_add(), ail_desktop_update()
1074  *
1075  * @par Prospective Clients:
1076  * External Apps.
1077  *
1078  * @code
1079 static ail_error_e _remove_desktop(const char *appid)
1080 {
1081         ail_error_e ret;
1082
1083         if (!appid) {
1084                 return AIL_ERROR_FAIL;
1085         }
1086
1087         ret = ail_desktop_remove(appid);
1088         if (ret != AIL_ERROR_OK) {
1089                 return AIL_ERROR_FAIL;
1090         }
1091
1092         return AIL_ERROR_OK;
1093 }
1094  * @endcode
1095  */
1096 ail_error_e ail_desktop_remove(const char *appid);
1097
1098 /** @} */
1099
1100
1101 #ifdef __cplusplus
1102 }
1103 #endif /* __cplusplus */
1104
1105 #endif /* __AIL_H__ */
1106 // End of a file