src/lib/efreet_desktop.h

   1 #ifndef EFREET_DESKTOP_H
   2 #define EFREET_DESKTOP_H
   3
   4 /**
   5  * @file efreet_desktop.h
   6  * @brief Contains the structures and methods used to support the
   7  *        FDO desktop entry specificiation.
   8  * @addtogroup Efreet_Desktop Efreet_Desktop: The FDO Desktop Entry
   9  *                  Specification functions and structures
  10  *
  11  * @{
  12  */
  13
  14
  15 /**
  16  * @param desktop the desktop entry
  17  * @param files an eina list of file names to execute, as either absolute paths,
  18  * relative paths, or uris
  19  * @param func a callback to call for each prepared command line
  20  * @param data user data passed to the callback
  21  * @return Returns the return value of @p func on success or NULL on failure
  22  * @brief Get a command to use to execute a desktop entry.
  23  */
  24 EAPI extern int EFREET_DESKTOP_TYPE_APPLICATION;
  25 EAPI extern int EFREET_DESKTOP_TYPE_LINK;
  26 EAPI extern int EFREET_DESKTOP_TYPE_DIRECTORY;
  27
  28 /**
  29  * Event id for cache update. All users of efreet_desktop_get must listen to
  30  * this event and refetch. The old eet cache will be closed and mem will
  31  * be invalidated.
  32  */
  33 EAPI extern int EFREET_EVENT_DESKTOP_CACHE_UPDATE;
  34 /**
  35  * Event id for cache build complete.
  36  * @since 1.1.0
  37  */
  38 EAPI extern int EFREET_EVENT_DESKTOP_CACHE_BUILD;
  39
  40 /**
  41  * Efreet_Desktop
  42  */
  43 typedef struct _Efreet_Desktop Efreet_Desktop;
  44
  45 /**
  46  * A callback used with efreet_desktop_command_get()
  47  */
  48 typedef void *(*Efreet_Desktop_Command_Cb) (void *data, Efreet_Desktop *desktop,
  49                                             char *command, int remaining);
  50
  51 /**
  52  * A callback used to get download progress of remote uris
  53  */
  54 typedef int (*Efreet_Desktop_Progress_Cb) (void *data, Efreet_Desktop *desktop,
  55                                             char *uri, long int total, long int current);
  56
  57 /**
  58  * A callback used to parse data for custom types
  59  */
  60 typedef void *(*Efreet_Desktop_Type_Parse_Cb) (Efreet_Desktop *desktop, Efreet_Ini *ini);
  61
  62 /**
  63  * A callback used to save data for custom types
  64  */
  65 typedef void (*Efreet_Desktop_Type_Save_Cb) (Efreet_Desktop *desktop, Efreet_Ini *ini);
  66
  67 /**
  68  * A callback used to free data for custom types
  69  */
  70 typedef void *(*Efreet_Desktop_Type_Free_Cb) (void *data);
  71
  72 /**
  73  * Efreet_Desktop
  74  * @brief a parsed representation of a .desktop file
  75  */
  76 struct _Efreet_Desktop
  77 {
  78     int type;               /**< type of desktop file */
  79
  80     int ref;                /**< reference count - internal */
  81
  82     char *version;          /**< version of spec file conforms to */
  83
  84     char *orig_path;        /**< original path to .desktop file */
  85     long long load_time;    /**< modified time of .desktop on disk */
  86
  87     char *name;             /**< Specific name of the application */
  88     char *generic_name;     /**< Generic name of the application */
  89     char *comment;          /**< Tooltip for the entry */
  90     char *icon;             /**< Icon to display in file manager, menus, etc */
  91     char *try_exec;         /**< Binary to determine if app is installed */
  92     char *exec;             /**< Program to execute */
  93     char *path;             /**< Working directory to run app in */
  94     char *startup_wm_class; /**< If specified will map at least one window with
  95                                 the given string as it's WM class or WM name */
  96     char *url;              /**< URL to access if type is EFREET_TYPE_LINK */
  97
  98     Eina_List  *only_show_in;   /**< list of environments that should
  99                                                     display the icon */
 100     Eina_List  *not_show_in;    /**< list of environments that shoudn't
 101                                                     display the icon */
 102     Eina_List  *categories;     /**< Categories in which item should be shown */
 103     Eina_List  *mime_types;     /**< The mime types supppored by this app */
 104
 105     unsigned char no_display;        /**< Don't display this application in menus */
 106     unsigned char hidden;            /**< User delete the item */
 107     unsigned char terminal;          /**< Does the program run in a terminal */
 108     unsigned char startup_notify;    /**< The starup notify settings of the app */
 109     unsigned char eet:1;             /**< The desktop file is in eet cache */
 110
 111     Eina_Hash *x; /**< Keep track of all user extensions, keys that begin with X- */
 112     void *type_data; /**< Type specific data for custom types */
 113 };
 114
 115
 116 /**
 117  * @param file The file to get the Efreet_Desktop from
 118  * @return Returns a reference to a cached Efreet_Desktop on success, NULL
 119  * on failure
 120  * @brief Gets a reference to an Efreet_Desktop structure representing the
 121  * contents of @a file or NULL if @a file is not a valid .desktop file.
 122  *
 123  * By using efreet_desktop_get the Efreet_Desktop will be saved in an internal
 124  * cache for quicker loading.
 125  *
 126  * Users of this command should listen to EFREET_EVENT_DESKTOP_CACHE_UPDATE
 127  * event, if the application is to keep the reference. When the event fires
 128  * the Efreet_Desktop struct should be invalidated and reloaded from a new
 129  * cache file.
 130  */
 131 EAPI Efreet_Desktop   *efreet_desktop_get(const char *file);
 132
 133 /**
 134  * @param desktop The Efreet_Desktop to ref
 135  * @return Returns the new reference count
 136  * @brief Increases reference count on desktop
 137  */
 138 EAPI int               efreet_desktop_ref(Efreet_Desktop *desktop);
 139
 140 /**
 141  * @param file The file to create the Efreet_Desktop from
 142  * @return Returns a new empty_Efreet_Desktop on success, NULL on failure
 143  * @brief Creates a new empty Efreet_Desktop structure or NULL on failure
 144  */
 145 EAPI Efreet_Desktop   *efreet_desktop_empty_new(const char *file);
 146
 147 /**
 148  * @param file The file to get the Efreet_Desktop from
 149  * @return Returns a reference to a cached Efreet_Desktop on success, NULL
 150  * on failure
 151  * @brief Gets a reference to an Efreet_Desktop structure representing the
 152  * contents of @a file or NULL if @a file is not a valid .desktop file.
 153  *
 154  * Users of this command should listen to EFREET_EVENT_DESKTOP_CACHE_UPDATE
 155  * event, if the application is to keep the reference. When the event fires
 156  * the Efreet_Desktop struct should be invalidated and reloaded from a new
 157  * cache file.
 158  */
 159 EAPI Efreet_Desktop   *efreet_desktop_new(const char *file);
 160
 161 /**
 162  * @param file The file to create the Efreet_Desktop from
 163  * @return Returns a new Efreet_Desktop on success, NULL on failure
 164  * @brief Creates a new Efreet_Desktop structure initialized from the
 165  * contents of @a file or NULL on failure
 166  *
 167  * By using efreet_desktop_uncached_new the Efreet_Desktop structure will be
 168  * read from disk, and not from any cache.
 169  *
 170  * Data in the structure is allocated with strdup, so use free and strdup to
 171  * change values.
 172  */
 173 EAPI Efreet_Desktop   *efreet_desktop_uncached_new(const char *file);
 174
 175 /**
 176  * @param desktop The Efreet_Desktop to work with
 177  * @return Returns no value
 178  * @brief Frees the Efreet_Desktop structure and all of it's data
 179  */
 180 EAPI void              efreet_desktop_free(Efreet_Desktop *desktop);
 181
 182 /**
 183  * @def efreet_desktop_unref(desktop)
 184  * Alias for efreet_desktop_free(desktop)
 185  */
 186 #define efreet_desktop_unref(desktop) efreet_desktop_free((desktop))
 187
 188
 189 /**
 190  * @param desktop The desktop file to save
 191  * @return Returns 1 on success or 0 on failure
 192  * @brief Saves any changes made to @a desktop back to the file on the
 193  * filesystem
 194  */
 195 EAPI int               efreet_desktop_save(Efreet_Desktop *desktop);
 196
 197 /**
 198  * @param desktop The desktop file to save
 199  * @param file The filename to save as
 200  * @return Returns 1 on success or 0 on failure
 201  * @brief Saves @a desktop to @a file
 202  *
 203  * Please use efreet_desktop_uncached_new() on an existing file
 204  * before using efreet_desktop_save_as()
 205  */
 206 EAPI int               efreet_desktop_save_as(Efreet_Desktop *desktop,
 207                                                 const char *file);
 208
 209
 210 /**
 211  * @param desktop The desktop file to work with
 212  * @param files The files to be substituted into the exec line
 213  * @param data The data pointer to pass
 214  * @return Returns the Ecore_Exce for @a desktop
 215  * @brief Parses the @a desktop exec line and returns an Ecore_Exe.
 216  */
 217 EAPI void              efreet_desktop_exec(Efreet_Desktop *desktop,
 218                                            Eina_List *files, void *data);
 219
 220
 221 /**
 222  * @param environment the environment name
 223  * @brief sets the global desktop environment name
 224  */
 225 EAPI void              efreet_desktop_environment_set(const char *environment);
 226
 227 /**
 228  * @return environment the environment name
 229  * @brief sets the global desktop environment name
 230  */
 231 EAPI const char       *efreet_desktop_environment_get(void);
 232
 233 /**
 234  * @param desktop the desktop entry
 235  * @param files an eina list of file names to execute, as either absolute paths,
 236  * relative paths, or uris
 237  * @param cb_command a callback to call for each prepared command line
 238  * @param cb_prog a callback to get progress for the downloads
 239  * @param data user data passed to the callback
 240  * @return Returns 1 on success or 0 on failure
 241  * @brief Get a command to use to execute a desktop entry, and receive progress
 242  * updates for downloading of remote URI's passed in.
 243  */
 244 EAPI void             *efreet_desktop_command_progress_get(Efreet_Desktop *desktop,
 245                                          Eina_List *files,
 246                                          Efreet_Desktop_Command_Cb cb_command,
 247                                          Efreet_Desktop_Progress_Cb cb_prog,
 248                                          void *data);
 249 EAPI void              *efreet_desktop_command_get(Efreet_Desktop *desktop,
 250                                          Eina_List *files,
 251                                          Efreet_Desktop_Command_Cb func,
 252                                          void *data);
 253
 254 /**
 255  * @param desktop the desktop entry
 256  * @param files an eina list of local files, as absolute paths, local paths, or file// uris (or NULL to get exec string with no files appended)
 257  * @return Returns an eina list of exec strings
 258  * @brief Get the command to use to execute a desktop entry
 259  *
 260  * The returned list and each of its elements must be freed.
 261  */
 262 EAPI Eina_List *      efreet_desktop_command_local_get(Efreet_Desktop *desktop,
 263                                          Eina_List *files);
 264
 265
 266 /**
 267  * @param desktop The desktop to work with
 268  * @return Returns the number of categories assigned to this desktop
 269  * @brief Retrieves the number of categories the given @a desktop belongs
 270  * too
 271  */
 272 EAPI unsigned int      efreet_desktop_category_count_get(Efreet_Desktop *desktop);
 273
 274 /**
 275  * @param desktop the desktop
 276  * @param category the category name
 277  * @brief add a category to a desktop
 278  */
 279 EAPI void              efreet_desktop_category_add(Efreet_Desktop *desktop,
 280                                               const char *category);
 281
 282 /**
 283  * @param desktop the desktop
 284  * @param category the category name
 285  * @brief removes a category from a desktop
 286  * @return 1 if the desktop had his category listed, 0 otherwise
 287  */
 288 EAPI int               efreet_desktop_category_del(Efreet_Desktop *desktop,
 289                                               const char *category);
 290
 291
 292 /**
 293  * @param type The type to add to the list of matching types
 294  * @param parse_func a function to parse out custom fields
 295  * @param save_func a function to save data returned from @a parse_func
 296  * @param free_func a function to free data returned from @a parse_func
 297  * @return Returns the id of the new type
 298  * @brief Adds the given type to the list of types in the system
 299  */
 300 EAPI int               efreet_desktop_type_add(const char *type,
 301                                     Efreet_Desktop_Type_Parse_Cb parse_func,
 302                                     Efreet_Desktop_Type_Save_Cb save_func,
 303                                     Efreet_Desktop_Type_Free_Cb free_func);
 304
 305 /**
 306  * @brief Add an alias for an existing desktop type.
 307  * @param from_type the type to alias (e.g. EFREE_DESKTOP_TYPE_APPLICATION)
 308  * @param alias the alias
 309  * @return the new type id, or -1 if @p from_type was not valid
 310  *
 311  * This allows applications to add non-standard types that behave exactly as standard types.
 312  */
 313 EAPI int               efreet_desktop_type_alias (int from_type,
 314                                              const char *alias);
 315
 316 /**
 317  * @brief get type specific data for custom desktop types
 318  * @param desktop the desktop
 319  * @return type specific data, or NULL if there is none
 320  */
 321 EAPI void             *efreet_desktop_type_data_get(Efreet_Desktop *desktop);
 322
 323
 324 /**
 325  * @param string the raw string list
 326  * @return an Eina_List of ecore string's
 327  * @brief Parse ';' separate list of strings according to the desktop spec
 328  */
 329 EAPI Eina_List        *efreet_desktop_string_list_parse(const char *string);
 330
 331 /**
 332  * @param list Eina_List with strings
 333  * @return a raw string list
 334  * @brief Create a ';' separate list of strings according to the desktop spec
 335  */
 336 EAPI char             *efreet_desktop_string_list_join(Eina_List *list);
 337
 338
 339 /**
 340  * @brief Set the value for a X- field (Non spec) in the structure
 341  * @param desktop the desktop
 342  * @param key the key name to set
 343  * @param data the value to set
 344  * @return EINA_TRUE on success
 345  *
 346  * The key has to start with "X-"
 347  */
 348 EAPI Eina_Bool         efreet_desktop_x_field_set(Efreet_Desktop *desktop, const char *key, const char *data);
 349
 350 /**
 351  * @brief Get the value for a X- field (Non spec) in the structure
 352  * @param desktop the desktop
 353  * @param key the key
 354  * @return The value referenced by the key, or NULL if the key does not exist
 355  */
 356 EAPI const char *      efreet_desktop_x_field_get(Efreet_Desktop *desktop, const char *key);
 357
 358 /**
 359  * @brief Delete the key and value for a X- field (Non spec) in the structure
 360  * @param desktop the desktop
 361  * @param key the key
 362  * @return EINA_TRUE if the key existed
 363  */
 364 EAPI Eina_Bool         efreet_desktop_x_field_del(Efreet_Desktop *desktop, const char *key);
 365
 366 /**
 367  * @}
 368  */
 369
 370 #endif