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