include/SLP_AIL_PG.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  @ingroup SLP_PG
  26  @defgroup SLP_PG_APPLICATION INFORMATION LIBRARY AIL
  27  @{
  28
  29 <h1 class="pg">Introduction</h1>
  30
  31 <h2 class="pg">Purpose of this document</h2>
  32  The purpose of this document is to describe how applications can use Application information library APIs to store/retrive the application's informations. This document gives programming guidelines to the application engineers.
  33
  34 <h2 class="pg">Scope</h2>
  35 The scope of this document is limited to AIL API usage.
  36
  37
  38 <h1 class="pg">Architecture</h1>
  39
  40 <h2 class="pg">Architecture overview</h2>
  41 Application information library manages the application information such as application name, type, icon path, exe path etc.
  42
  43 @image html SLP_ail_logical_view.png
  44
  45 <h2 class="pg">SLP Features</h2>
  46 - The Application information library provides installed applications informations.
  47 - The Application information library exposes the APIs to filter the applcation based on certain fields.
  48 - The Application information library uses DB to store the informations of the application.
  49 - The Application information library can process the desktop file to store/retrive the informations.
  50
  51
  52 <h1 class="pg">Application information library properties</h1>
  53
  54 <h2 class="pg">AIL Functionality</h2>
  55 There are three types of API's provided by AIL
  56 - ail_appinfo_xxx
  57         - Get the informations of the given package.
  58 - ail_filter_xxx
  59         - Get the Application informations matched to filter condition.
  60 - ail_desktop_xxx
  61         - add, update or remove package informations in DB.
  62
  63 <h2 class="pg">Software Components</h2>
  64 - Query Requester
  65         - It provides the interface to the DB. It is responsible for forming the query and excute the query in db.
  66 - Desktop file Reader/parser
  67         - It can read the application's desktop file from the file system (/opt/share/application/).
  68 - Filter
  69         - It can filter the query based on the given condition and it returns the filtered output to the application.
  70 - Get App info
  71         - It can get the information of the application using appid.
  72
  73 <h1 class="pg"> Software module Details </h2>
  74
  75 <h2 class="pg"> Query Requester </h2>
  76         - Query Requester module is provides the interface to sql DB in AIL.
  77         - It is responsible for creating connection to the DB, form the sql query and execute the query in DB.
  78         - It uses the libsql API to access the DB. (Eg) db_xx() API.
  79
  80 @code
  81
  82 @brief string type properties
  83
  84 #define AIL_PROP_PACKAGE_STR                    "AIL_PROP_PACKAGE_STR"
  85 #define AIL_PROP_EXEC_STR                       "AIL_PROP_EXEC_STR"
  86 #define AIL_PROP_NAME_STR                       "AIL_PROP_NAME_STR"
  87 #define AIL_PROP_TYPE_STR                       "AIL_PROP_TYPE_STR"
  88 #define AIL_PROP_ICON_STR                       "AIL_PROP_ICON_STR"
  89 #define AIL_PROP_CATEGORIES_STR                 "AIL_PROP_CATEGORIES_STR"
  90 #define AIL_PROP_VERSION_STR                    "AIL_PROP_VERSION_STR"
  91 #define AIL_PROP_MIMETYPE_STR                   "AIL_PROP_MIMETYPE_STR"
  92 #define AIL_PROP_X_SLP_SERVICE_STR              "AIL_PROP_X_SLP_SERVICE_STR"
  93 #define AIL_PROP_X_SLP_PACKAGETYPE_STR          "AIL_PROP_X_SLP_PACKAGETYPE_STR"
  94 #define AIL_PROP_X_SLP_PACKAGECATEGORIES_STR    "AIL_PROP_X_SLP_PACKAGECATEGORIES_STR"
  95 #define AIL_PROP_X_SLP_PACKAGEID_STR            "AIL_PROP_X_SLP_PACKAGEID_STR"
  96 #define AIL_PROP_X_SLP_SVC_STR                  "AIL_PROP_X_SLP_SVC_STR"
  97 #define AIL_PROP_X_SLP_EXE_PATH                 "AIL_PROP_X_SLP_EXE_PATH"
  98 #define AIL_PROP_X_SLP_APPID_STR                "AIL_PROP_X_SLP_APPID_STR"
  99
 100
 101 @brief integer type properties
 102
 103 #define AIL_PROP_X_SLP_TEMP_INT                 "AIL_PROP_X_SLP_TEMP_INT"
 104 #define AIL_PROP_X_SLP_INSTALLEDTIME_INT        "AIL_PROP_X_SLP_INSTALLEDTIME_INT"
 105
 106 @brief boolean type properties
 107
 108 #define AIL_PROP_NODISPLAY_BOOL                 "AIL_PROP_NODISPLAY_BOOL"
 109 #define AIL_PROP_X_SLP_TASKMANAGE_BOOL          "AIL_PROP_X_SLP_TASKMANAGE_BOOL"
 110 #define AIL_PROP_X_SLP_MULTIPLE_BOOL            "AIL_PROP_X_SLP_MULTIPLE_BOOL"
 111 #define AIL_PROP_X_SLP_REMOVABLE_BOOL           "AIL_PROP_X_SLP_REMOVABLE_BOOL"
 112 #define AIL_PROP_X_SLP_ENABLED_BOOL         "AIL_PROP_X_SLP_ENABLED_BOOL"
 113
 114
 115 @brief A handle for filters
 116
 117 typedef struct ail_filter *ail_filter_h;
 118
 119 @brief A handle for appinfos
 120
 121 typedef struct ail_appinfo *ail_appinfo_h;
 122
 123 @endcode
 124
 125
 126 <h2 class="pg">Desktop file Reader/parser</h2>
 127         - This module provides set of APIs to add update delete application's desktop files contents in DB.
 128         - It is responsible for validate the desktop file contents are in standard format.
 129         - The major functionality of this module is add, update and delete desktop file contents in DB Eg.(ail_desktop_xxx())
 130         <h3 class="pg"> Desktop file specification </h3>
 131                 - http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#introduction
 132                 - Desktop entry files should have the .desktop extension
 133                 - Entries in the file are {key,value} pairs in the format: Key=Value
 134                 - Standard Keys
 135                 - Type, Version, Name, NoDisplay, Icon, Hidden, Exec, Path, MimeType, Categories, URL, etc
 136                 - The Exec key must contain a command line. A command line consists of an executable program optionally followed by one or more arguments.
 137                 - The executable program can either be specified with its full path or with the name of the executable only.
 138                 - If no full path is provided the executable is looked up in the $PATH environment variable used by the desktop environment.
 139                 - The name or path of the executable program may not contain the equal sign ("="). Arguments are separated by a space.
 140
 141 @image html SLP_AIL_desktop.png
 142
 143 <h2 class="pg"> Adding desktop file to DB </h2>
 144 @image html SLP_AIL_add.png
 145 <h2 class="pg" > Sample code </h2>
 146 @code
 147 static ail_error_e _add_desktop(const char *package)
 148 {
 149         ail_error_e ret;
 150
 151         if (!package) {
 152                 return AIL_ERROR_FAIL;
 153         }
 154
 155         ret = ail_desktop_add(package);
 156         if (ret != AIL_ERROR_OK) {
 157                 return AIL_ERROR_FAIL;
 158         }
 159
 160         return AIL_ERROR_OK;
 161 }
 162
 163 static ail_error_e _remove_desktop(const char *package)
 164 {
 165         ail_error_e ret;
 166
 167         if (!package) {
 168                 return AIL_ERROR_FAIL;
 169         }
 170
 171         ret = ail_desktop_remove(package);
 172         if (ret != AIL_ERROR_OK) {
 173                 return AIL_ERROR_FAIL;
 174         }
 175
 176         return AIL_ERROR_OK;
 177 }
 178
 179 @endcode
 180
 181 <h2 class="pg">Filter</h2>
 182 This module provides set of APIs to get the information from the DB based on the given matched condtion.
 183 It is reponsbile for giving the filtered output to the applications. Eg.(ail_filter_xxx())  These following are some of the filtering condition.
 184         - Filter integer type only
 185         - Filter string type only
 186         - Filter bool type only
 187
 188 <h3 class="pg" > Filter sample code </h3>
 189 @code
 190 ail_cb_ret_e appinfo_func(const ail_appinfo_h appinfo, void *user_data)
 191 {
 192         int *i = (int *)user_data;
 193         char *package;
 194
 195         ail_appinfo_get_str(appinfo, AIL_PROP_PACKAGE_STR, &package);
 196         printf("i=%d %s\n", (*i)++, package);
 197
 198         if (*i > 30)
 199                 return AIL_CB_RET_CANCEL;
 200
 201         return AIL_CB_RET_CONTINUE;
 202 }
 203
 204 int list_packages()
 205 {
 206         ail_filter_h filter;
 207         ail_error_e ret;
 208         int i=0;
 209
 210         ret = ail_filter_new(&filter);
 211         if (ret != AIL_ERROR_OK) {
 212                 return -1;
 213         }
 214
 215         ret = ail_filter_add_bool(filter, AIL_PROP_X_SLP_REMOVABLE_BOOL, true);
 216         if (ret != AIL_ERROR_OK) {
 217                 return -1;
 218         }
 219
 220         ret = ail_filter_add_str(filter, AIL_PROP_TYPE_STR, "Application");
 221         if (ret != AIL_ERROR_OK) {
 222                 return -1;
 223         }
 224
 225         printf("List packages which are removable and 'Application' typed\n");
 226         ail_filter_list_appinfo_foreach(filter, appinfo_func, (void *)&i);
 227
 228         ail_filter_destroy(filter);
 229
 230         return 0;
 231 }
 232
 233 @endcode
 234
 235 <h2 class="pg">Get Application info</h2>
 236         - This module provides set of APIs to get informations of the installed packages.
 237         - This module internally uses the query Requester module to get the information of the requested packages in DB. Eg.(ail_appinfo_xxx())
 238 @image html SLP_AIL_get.png
 239
 240 @code
 241 static ail_error_e _get_name(const char *package)
 242 {
 243         ail_appinfo_h handle;
 244         ail_error_e ret;
 245         char *str;
 246
 247         ret = ail_package_get_appinfo(package, &handle);
 248         if (ret != AIL_ERROR_OK) {
 249                 return AIL_ERROR_FAIL;
 250         }
 251
 252         ret = ail_appinfo_get_str(handle, AIL_PROP_NAME_STR, &str);
 253         if (ret != AIL_ERROR_OK) {
 254                 return AIL_ERROR_FAIL;
 255         }
 256         fprintf(stderr, "Package[%s], Property[%s] : %s\n", package, property, str);
 257
 258         ret = ail_package_destroy_appinfo(handle);
 259         if (ret != AIL_ERROR_OK) {
 260                 return AIL_ERROR_FAIL;
 261         }
 262
 263         return AIL_ERROR_OK;
 264 }
 265
 266 @endcode
 267
 268
 269  @}
 270 **/