Efreet_Desktop: The FDO Desktop Entry
Efreet

Specification functions and structures More...

## Data Structures

struct | _Efreet_Desktop_Action
| Efreet_Desktop_Action. More...
struct | _Efreet_Desktop
| Efreet_Desktop. More...

## Macros

#define | efreet_desktop_unref(desktop)
| Alias for efreet_desktop_free(desktop).

## Typedefs

typedef struct _Efreet_Desktop_Action | Efreet_Desktop_Action
| Efreet_Desktop_Action.
typedef struct _Efreet_Desktop | Efreet_Desktop
| Efreet_Desktop.
typedef void *(* | Efreet_Desktop_Command_Cb) (void *data, Efreet_Desktop *desktop, char *command, int remaining)
| A callback used with efreet_desktop_command_get().
typedef int(* | Efreet_Desktop_Progress_Cb) (void *data, Efreet_Desktop *desktop, char *uri, long int total, long int current)
| A callback used to get download progress of remote uris.
typedef void *(* | Efreet_Desktop_Type_Parse_Cb) (Efreet_Desktop *desktop, Efreet_Ini *ini)
| A callback used to parse data for custom types.
typedef void(* | Efreet_Desktop_Type_Save_Cb) (Efreet_Desktop *desktop, Efreet_Ini *ini)
| A callback used to save data for custom types.
typedef void *(* | Efreet_Desktop_Type_Free_Cb) (void *data)
| A callback used to free data for custom types.

## Functions

Efreet_Desktop * | efreet_desktop_get (const char *file)
| Gets a reference to an Efreet_Desktop structure representing the contents of file or NULL if file is not a valid .desktop file.
int | efreet_desktop_ref (Efreet_Desktop *desktop)
| Increases reference count on desktop.
Efreet_Desktop * | efreet_desktop_empty_new (const char *file)
| Creates a new empty Efreet_Desktop structure or NULL on failure.
Efreet_Desktop * | efreet_desktop_new (const char *file)
| Gets a reference to an Efreet_Desktop structure representing the contents of file or NULL if file is not a valid .desktop file.
Efreet_Desktop * | efreet_desktop_uncached_new (const char *file)
| Creates a new Efreet_Desktop structure initialized from the contents of file or NULL on failure.
void | efreet_desktop_free (Efreet_Desktop *desktop)
| Frees the Efreet_Desktop structure and all of it's data.
int | efreet_desktop_save (Efreet_Desktop *desktop)
| Saves any changes made to desktop back to the file on the filesystem.
int | efreet_desktop_save_as (Efreet_Desktop *desktop, const char *file)
| Saves desktop to file.
void | efreet_desktop_exec (Efreet_Desktop *desktop, Eina_List *files, void *data)
| Parses the desktop exec line and runs the command.
void | efreet_desktop_environment_set (const char *environment)
| sets the global desktop environment name
const char * | efreet_desktop_environment_get (void)
| gets the global desktop environment name (e.g. "Enlightenment" or "Gnome")
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)
| Get a command to use to execute a desktop entry, and receive progress updates for downloading of remote URI's passed in.
void * | efreet_desktop_command_get (Efreet_Desktop *desktop, Eina_List *files, Efreet_Desktop_Command_Cb func, void *data)
| Get a command to use to execute a desktop entry.
Eina_List * | efreet_desktop_command_local_get (Efreet_Desktop *desktop, Eina_List *files)
| Get the command to use to execute a desktop entry.
unsigned int | efreet_desktop_category_count_get (Efreet_Desktop *desktop)
| Retrieves the number of categories the given desktop belongs too.
void | efreet_desktop_category_add (Efreet_Desktop *desktop, const char *category)
| add a category to a desktop
int | efreet_desktop_category_del (Efreet_Desktop *desktop, const char *category)
| removes a category from a desktop
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)
| Adds the given type to the list of types in the system.
int | efreet_desktop_type_alias (int from_type, const char *alias)
| Add an alias for an existing desktop type.
void * | efreet_desktop_type_data_get (Efreet_Desktop *desktop)
| get type specific data for custom desktop types
Eina_List * | efreet_desktop_string_list_parse (const char *string)
| Parse ';' separate list of strings according to the desktop spec.
char * | efreet_desktop_string_list_join (Eina_List *list)
| Create a ';' separate list of strings according to the desktop spec.
Eina_Bool | efreet_desktop_x_field_set (Efreet_Desktop *desktop, const char *key, const char *data)
| Set the value for a X- field (Non spec) in the structure.
const char * | efreet_desktop_x_field_get (Efreet_Desktop *desktop, const char *key)
| Get the value for a X- field (Non spec) in the structure.
Eina_Bool | efreet_desktop_x_field_del (Efreet_Desktop *desktop, const char *key)
| Delete the key and value for a X- field (Non spec) in the structure.

## Variables

int | EFREET_DESKTOP_TYPE_APPLICATION
int | EFREET_DESKTOP_TYPE_LINK
int | EFREET_DESKTOP_TYPE_DIRECTORY
int | EFREET_EVENT_DESKTOP_CACHE_UPDATE
| Event id for cache update.
int | EFREET_EVENT_DESKTOP_CACHE_BUILD
| Event id for cache build complete.

## Detailed Description

Specification functions and structures

## Macro Definition Documentation

## efreet_desktop_unref

#define efreet_desktop_unref | ( |  | desktop | ) |

Value:
efreet_desktop_free((desktop))
efreet_desktop_free
void efreet_desktop_free(Efreet_Desktop *desktop)
Frees the Efreet_Desktop structure and all of it's data.
Definition efreet_desktop.c:367

Alias for efreet_desktop_free(desktop).

## Typedef Documentation

## Efreet_Desktop_Action

typedef struct _Efreet_Desktop_Action Efreet_Desktop_Action

Efreet_Desktop_Action.

Since
  1.12

## Function Documentation

## efreet_desktop_get()

Efreet_Desktop * efreet_desktop_get | ( | const char * | file | ) |

Gets a reference to an Efreet_Desktop structure representing the contents of file or NULL if file is not a valid .desktop file.

Parameters

  file | The file to get the Efreet_Desktop from

Returns
  Returns a reference to a cached Efreet_Desktop on success, NULL on failure

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.

References ecore_file_readlink(), _Efreet_Desktop::eet, efreet_desktop_free(), efreet_desktop_new(), eina_list_nth(), EINA_SAFETY_ON_NULL_RETURN_VAL, and _Efreet_Desktop::type.

Referenced by efreet_util_desktop_exec_find(), efreet_util_desktop_exec_glob_list(), and efreet_util_desktop_file_id_find().

## efreet_desktop_ref()

int efreet_desktop_ref | ( | Efreet_Desktop * | desktop | ) |

Increases reference count on desktop.

Parameters

  desktop | The Efreet_Desktop to ref

Returns
  Returns the new reference count

References EINA_SAFETY_ON_NULL_RETURN_VAL, and _Efreet_Desktop::ref.

Referenced by efreet_menu_desktop_insert().

## efreet_desktop_empty_new()

Efreet_Desktop * efreet_desktop_empty_new | ( | const char * | file | ) |

Creates a new empty Efreet_Desktop structure or NULL on failure.

Parameters

  file | The file to create the Efreet_Desktop from

Returns
  Returns a new empty_Efreet_Desktop on success, NULL on failure

References EINA_SAFETY_ON_NULL_RETURN_VAL, _Efreet_Desktop::load_time, _Efreet_Desktop::orig_path, and _Efreet_Desktop::ref.

## efreet_desktop_new()

Efreet_Desktop * efreet_desktop_new | ( | const char * | file | ) |

Gets a reference to an Efreet_Desktop structure representing the contents of file or NULL if file is not a valid .desktop file.

Parameters

  file | The file to get the Efreet_Desktop from

Returns
  Returns a reference to a cached Efreet_Desktop on success, NULL on failure

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.

References efreet_desktop_free(), efreet_desktop_uncached_new(), eina_file_path_sanitize(), EINA_SAFETY_ON_NULL_RETURN_VAL, and _Efreet_Desktop::ref.

Referenced by efreet_desktop_get().

## efreet_desktop_uncached_new()

Efreet_Desktop * efreet_desktop_uncached_new | ( | const char * | file | ) |

Creates a new Efreet_Desktop structure initialized from the contents of file or NULL on failure.

Parameters

  file | The file to create the Efreet_Desktop from

Returns
  Returns a new Efreet_Desktop on success, 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.

References ecore_file_exists(), efreet_desktop_free(), eina_file_path_sanitize(), EINA_SAFETY_ON_NULL_RETURN_VAL, _Efreet_Desktop::orig_path, and _Efreet_Desktop::ref.

Referenced by efreet_desktop_new().

## efreet_desktop_free()

void efreet_desktop_free | ( | Efreet_Desktop * | desktop | ) |

Frees the Efreet_Desktop structure and all of it's data.

Parameters

  desktop | The Efreet_Desktop to work with

Returns
  Returns no value

References _Efreet_Desktop::actions, _Efreet_Desktop::categories, _Efreet_Desktop::comment, _Efreet_Desktop::eet, EINA_LIST_FREE, eina_list_nth(), eina_stringshare_del(), _Efreet_Desktop::exec, _Efreet_Desktop_Action::exec, _Efreet_Desktop::generic_name, _Efreet_Desktop::icon, _Efreet_Desktop_Action::icon, _Efreet_Desktop::implements, _Efreet_Desktop_Action::key, _Efreet_Desktop::keywords, _Efreet_Desktop::mime_types, _Efreet_Desktop::name, _Efreet_Desktop_Action::name, _Efreet_Desktop::not_show_in, _Efreet_Desktop::only_show_in, _Efreet_Desktop::orig_path, _Efreet_Desktop::path, _Efreet_Desktop::ref, _Efreet_Desktop::startup_wm_class, _Efreet_Desktop::try_exec, _Efreet_Desktop::type, _Efreet_Desktop::type_data, _Efreet_Desktop::url, _Efreet_Desktop::version, and _Efreet_Desktop::x.

Referenced by efreet_desktop_get(), efreet_desktop_new(), efreet_desktop_uncached_new(), and efreet_menu_free().

## efreet_desktop_save()

int efreet_desktop_save | ( | Efreet_Desktop * | desktop | ) |

Saves any changes made to desktop back to the file on the filesystem.

Parameters

  desktop | The desktop file to save

Returns
  Returns 1 on success or 0 on failure

References efreet_desktop_string_list_join(), eina_list_nth(), EINA_SAFETY_ON_NULL_RETURN_VAL, _Efreet_Desktop::not_show_in, _Efreet_Desktop::only_show_in, _Efreet_Desktop::orig_path, and _Efreet_Desktop::type.

Referenced by efreet_desktop_save_as().

## efreet_desktop_save_as()

int efreet_desktop_save_as | ( | Efreet_Desktop * | desktop,
|  | const char * | file )

Saves desktop to file.

Parameters

  desktop | The desktop file to save
  file | The filename to save as

Returns
  Returns 1 on success or 0 on failure

Please use efreet_desktop_uncached_new() on an existing file before using efreet_desktop_save_as()

References _Efreet_Desktop::eet, efreet_desktop_save(), EINA_SAFETY_ON_NULL_RETURN_VAL, and _Efreet_Desktop::orig_path.

## efreet_desktop_exec()

void efreet_desktop_exec | ( | Efreet_Desktop * | desktop,
|  | Eina_List * | files,
|  | void * | data )

Parses the desktop exec line and runs the command.

Parameters

  desktop | The desktop file to work with
  files | The files to be substituted into the exec line
  data | The data pointer to pass

References efreet_desktop_command_get().

## efreet_desktop_environment_set()

void efreet_desktop_environment_set | ( | const char * | environment | ) |

sets the global desktop environment name

Parameters

  environment | the environment name

References eina_stringshare_replace().

## efreet_desktop_environment_get()

const char * efreet_desktop_environment_get | ( | void |  | ) |

gets the global desktop environment name (e.g. "Enlightenment" or "Gnome")

Returns
  environment the environment name

Referenced by efreet_mime_type_icon_get().

## efreet_desktop_command_progress_get()

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 )

Get a command to use to execute a desktop entry, and receive progress updates for downloading of remote URI's passed in.

Parameters

  desktop | the desktop entry
  files | an eina list of file names to execute, as either absolute paths, relative paths, or uris
  cb_command | a callback to call for each prepared command line
  cb_prog | a callback to get progress for the downloads
  data | user data passed to the callback

Returns
  Returns 1 on success or 0 on failure

References eina_list_append(), EINA_LIST_FOREACH, eina_list_free(), EINA_SAFETY_ON_NULL_RETURN_VAL, and _Efreet_Desktop::exec.

Referenced by efreet_desktop_command_get().

## efreet_desktop_command_get()

void * efreet_desktop_command_get | ( | Efreet_Desktop * | desktop,
|  | Eina_List * | files,
|  | Efreet_Desktop_Command_Cb | func,
|  | void * | data )

Get a command to use to execute a desktop entry.

Parameters

  desktop | the desktop entry
  files | an eina list of file names to execute, as either absolute paths, relative paths, or uris
  func | a callback to call for each prepared command line
  data | user data passed to the callback

Returns
  Returns the return value of `func` on success or NULL on failure

References efreet_desktop_command_progress_get().

Referenced by efreet_desktop_exec().

## efreet_desktop_command_local_get()

Eina_List * efreet_desktop_command_local_get | ( | Efreet_Desktop * | desktop,
|  | Eina_List * | files )

Get the command to use to execute a desktop entry.

Parameters

  desktop | the desktop entry
  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)

Returns
  Returns an eina list of exec strings

The returned list and each of its elements must be freed.

References eina_list_append(), EINA_LIST_FOREACH, EINA_SAFETY_ON_NULL_RETURN_VAL, and _Efreet_Desktop::exec.

## efreet_desktop_category_count_get()

unsigned int efreet_desktop_category_count_get | ( | Efreet_Desktop * | desktop | ) |

Retrieves the number of categories the given desktop belongs too.

Parameters

  desktop | The desktop to work with

Returns
  Returns the number of categories assigned to this desktop

References _Efreet_Desktop::categories, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## efreet_desktop_category_add()

void efreet_desktop_category_add | ( | Efreet_Desktop * | desktop,
|  | const char * | category )

add a category to a desktop

Parameters

  desktop | the desktop
  category | the category name

References _Efreet_Desktop::categories, EINA_COMPARE_CB, eina_list_append(), eina_list_search_unsorted(), EINA_SAFETY_ON_NULL_RETURN, and eina_stringshare_add().

## efreet_desktop_category_del()

int efreet_desktop_category_del | ( | Efreet_Desktop * | desktop,
|  | const char * | category )

removes a category from a desktop

Parameters

  desktop | the desktop
  category | the category name

Returns
  1 if the desktop had his category listed, 0 otherwise

References _Efreet_Desktop::categories, EINA_COMPARE_CB, eina_list_remove(), eina_list_search_unsorted(), EINA_SAFETY_ON_NULL_RETURN_VAL, and eina_stringshare_del().

## efreet_desktop_type_add()

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 )

Adds the given type to the list of types in the system.

Parameters

  type | The type to add to the list of matching types
  parse_func | a function to parse out custom fields
  save_func | a function to save data returned from parse_func
  free_func | a function to free data returned from parse_func

Returns
  Returns the id of the new type

References eina_list_append(), and eina_stringshare_add().

Referenced by efreet_desktop_type_alias().

## efreet_desktop_type_alias()

int efreet_desktop_type_alias | ( | int | from_type,
|  | const char * | alias )

Add an alias for an existing desktop type.

Parameters

  from_type | the type to alias (e.g. EFREE_DESKTOP_TYPE_APPLICATION)
  alias | the alias

Returns
  the new type id, or -1 if `from_type` was not valid

This allows applications to add non-standard types that behave exactly as standard types.

References efreet_desktop_type_add(), and eina_list_nth().

## efreet_desktop_type_data_get()

void * efreet_desktop_type_data_get | ( | Efreet_Desktop * | desktop | ) |

get type specific data for custom desktop types

Parameters

  desktop | the desktop

Returns
  type specific data, or NULL if there is none

References EINA_SAFETY_ON_NULL_RETURN_VAL, and _Efreet_Desktop::type_data.

## efreet_desktop_string_list_parse()

Eina_List * efreet_desktop_string_list_parse | ( | const char * | string | ) |

Parse ';' separate list of strings according to the desktop spec.

Parameters

  string | the raw string list

Returns
  an Eina_List of ecore string's

References alloca(), eina_list_append(), EINA_SAFETY_ON_NULL_RETURN_VAL, eina_stringshare_add(), and WRN.

## efreet_desktop_string_list_join()

char * efreet_desktop_string_list_join | ( | Eina_List * | list | ) |

Create a ';' separate list of strings according to the desktop spec.

Parameters

  list | Eina_List with strings

Returns
  a raw string list

References EINA_LIST_FOREACH.

Referenced by efreet_desktop_save().

## efreet_desktop_x_field_set()

Eina_Bool efreet_desktop_x_field_set | ( | Efreet_Desktop * | desktop,
|  | const char * | key,
|  | const char * | data )

Set the value for a X- field (Non spec) in the structure.

Parameters

  desktop | the desktop
  key | the key name to set
  data | the value to set

Returns
  EINA_TRUE on success

The key has to start with "X-"

References EINA_FALSE, EINA_FREE_CB, eina_hash_add(), eina_hash_del_by_key(), eina_hash_string_superfast_new(), EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, eina_stringshare_add(), eina_stringshare_del(), EINA_TRUE, and _Efreet_Desktop::x.

## efreet_desktop_x_field_get()

const char * efreet_desktop_x_field_get | ( | Efreet_Desktop * | desktop,
|  | const char * | key )

Get the value for a X- field (Non spec) in the structure.

Parameters

  desktop | the desktop
  key | the key

Returns
  The value referenced by the key, or NULL if the key does not exist

References efreet_desktop_x_field_del(), eina_hash_find(), EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, eina_stringshare_add(), eina_stringshare_replace(), and _Efreet_Desktop::x.

## efreet_desktop_x_field_del()

Eina_Bool efreet_desktop_x_field_del | ( | Efreet_Desktop * | desktop,
|  | const char * | key )

Delete the key and value for a X- field (Non spec) in the structure.

Parameters

  desktop | the desktop
  key | the key

Returns
  EINA_TRUE if the key existed

References EINA_FALSE, eina_hash_del_by_key(), EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, and _Efreet_Desktop::x.

Referenced by efreet_desktop_x_field_get().

## Variable Documentation

## EFREET_EVENT_DESKTOP_CACHE_UPDATE

int EFREET_EVENT_DESKTOP_CACHE_UPDATE

extern

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.

## EFREET_EVENT_DESKTOP_CACHE_BUILD

int EFREET_EVENT_DESKTOP_CACHE_BUILD

extern

Event id for cache build complete.

Since
  1.1.0