aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/efreet/efreet_desktop.h
blob: fe9512465421879ce796cab3512fd8d23c14308b (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
#ifndef EFREET_DESKTOP_H
#define EFREET_DESKTOP_H

/**
 * @file efreet_desktop.h
 * @brief Contains the structures and methods used to support the
 *        FDO desktop entry specificiation.
 *
 * @internal
 * @defgroup Efreet_Desktop_Group Efreet_Desktop: The FDO Desktop Entry
 *           Specification functions and structures
 * @ingroup Efreet_Group
 *
 * @{
 */


EAPI extern int EFREET_DESKTOP_TYPE_APPLICATION;
EAPI extern int EFREET_DESKTOP_TYPE_LINK;
EAPI extern int EFREET_DESKTOP_TYPE_DIRECTORY;

/**
 * Event id for cache update. All users of efreet_desktop_get must listen to
 * this event and refetch. The old eet cache will be closed and mem will
 * be invalidated.
 */
EAPI extern int EFREET_EVENT_DESKTOP_CACHE_UPDATE;
/**
 * Event id for cache build complete.
 * @since 1.1.0
 */
EAPI extern int EFREET_EVENT_DESKTOP_CACHE_BUILD;

/**
 * Efreet_Desktop
 */
typedef struct _Efreet_Desktop Efreet_Desktop;

/**
 * A callback used with efreet_desktop_command_get()
 */
typedef void *(*Efreet_Desktop_Command_Cb) (void *data, Efreet_Desktop *desktop,
                                            char *command, int remaining);

/**
 * A callback used to get download progress of remote uris
 */
typedef int (*Efreet_Desktop_Progress_Cb) (void *data, Efreet_Desktop *desktop,
                                            char *uri, long int total, long int current);

/**
 * A callback used to parse data for custom types
 */
typedef void *(*Efreet_Desktop_Type_Parse_Cb) (Efreet_Desktop *desktop, Efreet_Ini *ini);

/**
 * A callback used to save data for custom types
 */
typedef void (*Efreet_Desktop_Type_Save_Cb) (Efreet_Desktop *desktop, Efreet_Ini *ini);

/**
 * A callback used to free data for custom types
 */
typedef void *(*Efreet_Desktop_Type_Free_Cb) (void *data);

/**
 * Efreet_Desktop
 * @brief a parsed representation of a .desktop file
 */
struct _Efreet_Desktop
{
    int type;               /**< type of desktop file */

    int ref;                /**< reference count - internal */

    char *version;          /**< version of spec file conforms to */

    char *orig_path;        /**< original path to .desktop file */
    long long load_time;    /**< modified time of .desktop on disk */

    char *name;             /**< Specific name of the application */
    char *generic_name;     /**< Generic name of the application */
    char *comment;          /**< Tooltip for the entry */
    char *icon;             /**< Icon to display in file manager, menus, etc */
    char *try_exec;         /**< Binary to determine if app is installed */
    char *exec;             /**< Program to execute */
    char *path;             /**< Working directory to run app in */
    char *startup_wm_class; /**< If specified will map at least one window with
                                the given string as it's WM class or WM name */
    char *url;              /**< URL to access if type is EFREET_TYPE_LINK */

    Eina_List  *only_show_in;   /**< list of environments that should
                                                    display the icon */
    Eina_List  *not_show_in;    /**< list of environments that shoudn't
                                                    display the icon */
    Eina_List  *categories;     /**< Categories in which item should be shown */
    Eina_List  *mime_types;     /**< The mime types supppored by this app */

    unsigned char no_display;        /**< Don't display this application in menus */
    unsigned char hidden;            /**< User delete the item */
    unsigned char terminal;          /**< Does the program run in a terminal */
    unsigned char startup_notify;    /**< The starup notify settings of the app */
    unsigned char eet:1;             /**< The desktop file is in eet cache */

    Eina_Hash *x; /**< Keep track of all user extensions, keys that begin with X- */
    void *type_data; /**< Type specific data for custom types */
};


/**
 * @brief Gets a reference to an Efreet_Desktop structure representing the
 * contents of @a file or NULL if @a file is not a valid .desktop file.
 *
 * By using efreet_desktop_get the Efreet_Desktop will be saved in an internal
 * cache for quicker loading.
 *
 * Users of this command should listen to EFREET_EVENT_DESKTOP_CACHE_UPDATE
 * event, if the application is to keep the reference. When the event fires
 * the Efreet_Desktop struct should be invalidated and reloaded from a new
 * cache file.
 *
 * @param[in] file The file to get the Efreet_Desktop from
 * @return Returns a reference to a cached Efreet_Desktop on success, NULL
 * on failure
 */
EAPI Efreet_Desktop   *efreet_desktop_get(const char *file);

/**
 * @brief Increases reference count on desktop
 *
 * @param[in] desktop The Efreet_Desktop to ref
 * @return Returns the new reference count
 */
EAPI int               efreet_desktop_ref(Efreet_Desktop *desktop);

/**
 * @brief Creates a new empty Efreet_Desktop structure or NULL on failure
 *
 * @param file The file to create the Efreet_Desktop from
 * @return Returns a new empty_Efreet_Desktop on success, NULL on failure
 */
EAPI Efreet_Desktop   *efreet_desktop_empty_new(const char *file);

/**
 * @brief Gets a reference to an Efreet_Desktop structure representing the
 * contents of @a file or NULL if @a file is not a valid .desktop file.
 *
 * Users of this command should listen to EFREET_EVENT_DESKTOP_CACHE_UPDATE
 * event, if the application is to keep the reference. When the event fires
 * the Efreet_Desktop struct should be invalidated and reloaded from a new
 * cache file.
 *
 * @param[in] file The file to get the Efreet_Desktop from
 * @return Returns a reference to a cached Efreet_Desktop on success, NULL
 * on failure
 */
EAPI Efreet_Desktop   *efreet_desktop_new(const char *file);

/**
 * @brief Creates a new Efreet_Desktop structure initialized from the
 * contents of @a file or NULL on failure
 *
 * By using efreet_desktop_uncached_new the Efreet_Desktop structure will be
 * read from disk, and not from any cache.
 *
 * Data in the structure is allocated with strdup, so use free and strdup to
 * change values.
 *
 * @param[in] file The file to create the Efreet_Desktop from
 * @return Returns a new Efreet_Desktop on success, NULL on failure
 */
EAPI Efreet_Desktop   *efreet_desktop_uncached_new(const char *file);

/**
 * @brief Frees the Efreet_Desktop structure and all of it's data
 *
 * @param[in] desktop The Efreet_Desktop to work with
 * @return Returns no value
 */
EAPI void              efreet_desktop_free(Efreet_Desktop *desktop);

/**
 * @def efreet_desktop_unref(desktop)
 * Alias for efreet_desktop_free(desktop)
 */
#define efreet_desktop_unref(desktop) efreet_desktop_free((desktop))


/**
 * @brief Saves any changes made to @a desktop back to the file on the
 * filesystem
 *
 * @param[in] desktop The desktop file to save
 * @return Returns 1 on success or 0 on failure
 */
EAPI int               efreet_desktop_save(Efreet_Desktop *desktop);

/**
 * @brief Saves @a desktop to @a file
 *
 * Please use efreet_desktop_uncached_new() on an existing file
 * before using efreet_desktop_save_as()
 *
 * @param[in] desktop The desktop file to save
 * @param[in] file The filename to save as
 * @return Returns 1 on success or 0 on failure
 */
EAPI int               efreet_desktop_save_as(Efreet_Desktop *desktop,
                                                const char *file);


/**
 * @brief Parses the @a desktop exec line and returns an Ecore_Exe.
 *
 * @param[in] desktop The desktop file to work with
 * @param[in] files The files to be substituted into the exec line
 * @param[in] data The data pointer to pass
 * @return Returns the Ecore_Exce for @a desktop
 */
EAPI void              efreet_desktop_exec(Efreet_Desktop *desktop,
                                           Eina_List *files, void *data);


/**
 * @brief sets the global desktop environment name
 *
 * @param[in] environment the environment name
 */
EAPI void              efreet_desktop_environment_set(const char *environment);

/**
 * @brief sets the global desktop environment name
 *
 * @return environment the environment name
 */
EAPI const char       *efreet_desktop_environment_get(void);

/**
 * @brief Get a command to use to execute a desktop entry, and receive progress
 * updates for downloading of remote URI's passed in.
 *
 * @param[in] desktop the desktop entry
 * @param[in] files an eina list of file names to execute, as either absolute paths,
 * relative paths, or uris
 * @param[in] cb_command a callback to call for each prepared command line
 * @param[in] cb_prog a callback to get progress for the downloads
 * @param[in] data user data passed to the callback
 * @return Returns 1 on success or 0 on failure
 */
EAPI void             *efreet_desktop_command_progress_get(Efreet_Desktop *desktop,
                                         Eina_List *files,
                                         Efreet_Desktop_Command_Cb cb_command,
                                         Efreet_Desktop_Progress_Cb cb_prog,
                                         void *data);
/**
 * @brief Get a command to use to execute a desktop entry.
 *
 * @param[in] desktop the desktop entry
 * @param[in] files an eina list of file names to execute, as either absolute paths,
 * relative paths, or uris
 * @param[in] func a callback to call for each prepared command line
 * @param[in] data user data passed to the callback
 * @return Returns the return value of @p func on success or NULL on failure
 */
EAPI void              *efreet_desktop_command_get(Efreet_Desktop *desktop,
                                         Eina_List *files,
                                         Efreet_Desktop_Command_Cb func,
                                         void *data);

/**
 * @brief Get the command to use to execute a desktop entry
 *
 * The returned list and each of its elements must be freed.
 *
 * @param[in] desktop the desktop entry
 * @param[in] 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)
 * @return Returns an eina list of exec strings
 */
EAPI Eina_List *      efreet_desktop_command_local_get(Efreet_Desktop *desktop,
                                         Eina_List *files);


/**
 * @brief Retrieves the number of categories the given @a desktop belongs
 * too
 *
 * @param[in] desktop The desktop to work with
 * @return Returns the number of categories assigned to this desktop
 */
EAPI unsigned int      efreet_desktop_category_count_get(Efreet_Desktop *desktop);

/**
 * @brief add a category to a desktop
 *
 * @param[in] desktop the desktop
 * @param[in] category the category name
 */
EAPI void              efreet_desktop_category_add(Efreet_Desktop *desktop,
                                              const char *category);

/**
 * @brief removes a category from a desktop
 *
 * @param[in] desktop the desktop
 * @param[in] category the category name
 * @return 1 if the desktop had his category listed, 0 otherwise
 */
EAPI int               efreet_desktop_category_del(Efreet_Desktop *desktop,
                                              const char *category);


/**
 * @brief Adds the given type to the list of types in the system
 *
 * @param[in] type The type to add to the list of matching types
 * @param[in] parse_func a function to parse out custom fields
 * @param[in] save_func a function to save data returned from @a parse_func
 * @param[in] free_func a function to free data returned from @a parse_func
 * @return Returns the id of the new type
 */
EAPI int               efreet_desktop_type_add(const char *type,
                                    Efreet_Desktop_Type_Parse_Cb parse_func,
                                    Efreet_Desktop_Type_Save_Cb save_func,
                                    Efreet_Desktop_Type_Free_Cb free_func);

/**
 * @brief Add an alias for an existing desktop type.
 *
 * @param[in] from_type the type to alias (e.g. EFREE_DESKTOP_TYPE_APPLICATION)
 * @param[in] alias the alias
 * @return the new type id, or -1 if @p from_type was not valid
 *
 * This allows applications to add non-standard types that behave exactly as standard types.
 */
EAPI int               efreet_desktop_type_alias (int from_type,
                                             const char *alias);

/**
 * @brief get type specific data for custom desktop types
 *
 * @param[in] desktop the desktop
 * @return type specific data, or NULL if there is none
 */
EAPI void             *efreet_desktop_type_data_get(Efreet_Desktop *desktop);


/**
 * @brief Parse ';' separate list of strings according to the desktop spec
 *
 * @param[in] string the raw string list
 * @return an Eina_List of ecore string's
 */
EAPI Eina_List        *efreet_desktop_string_list_parse(const char *string);

/**
 * @brief Create a ';' separate list of strings according to the desktop spec
 *
 * @param[in] list Eina_List with strings
 * @return a raw string list
 */
EAPI char             *efreet_desktop_string_list_join(Eina_List *list);


/**
 * @brief Set the value for a X- field (Non spec) in the structure
 *
 * @param[in] desktop the desktop
 * @param[in] key the key name to set
 * @param[in] data the value to set
 * @return EINA_TRUE on success
 *
 * The key has to start with "X-"
 */
EAPI Eina_Bool         efreet_desktop_x_field_set(Efreet_Desktop *desktop, const char *key, const char *data);

/**
 * @brief Get the value for a X- field (Non spec) in the structure
 *
 * @param[in] desktop the desktop
 * @param[in] key the key
 * @return The value referenced by the key, or NULL if the key does not exist
 */
EAPI const char *      efreet_desktop_x_field_get(Efreet_Desktop *desktop, const char *key);

/**
 * @brief Delete the key and value for a X- field (Non spec) in the structure
 *
 * @param[in] desktop the desktop
 * @param[in] key the key
 * @return EINA_TRUE if the key existed
 */
EAPI Eina_Bool         efreet_desktop_x_field_del(Efreet_Desktop *desktop, const char *key);

/**
 * @}
 */

#endif