1 <!-- ##### SECTION ./tmpl/desktop_entry.sgml:Long_Description ##### -->
3 The "GDesktopEntry" parser is intended to parse files written to
5 url="http://www.freedesktop.org/Standards/desktop-entry-spec">Desktop
6 Entry Specification</ulink>. It supports deserialization of
7 desktop entries from files and in-memory data. Desktop entries
8 are used for a variety of things including menus, application
9 MIME type registration, and launchers.
13 To load an existing desktop entry from a data directory (as
14 returned by g_get_user_data_dir() and g_get_system_data_dirs())
15 use g_desktop_entry_new_from_data_dirs(). To load an existing
16 desktop entry from an arbitrary location on the file system use
17 g_desktop_entry_new_from_file(). If the desktop entry is already
18 in memory use g_desktop_entry_new_from_data(). Once the desktop
19 entry is loaded its keys can be queried using the g_desktop_entry_get
24 To create a new desktop entry first call g_desktop_entry_new().
25 Then, call the g_desktop_entry_set family of functions. Next,
26 call g_desktop_entry_to_data() to output the desktop entry to
27 a byte array, which can be written to disk or sent over a
28 network. Finally, call g_desktop_entry_free() to deallocate the
29 #GDesktopEntry object returned by g_desktop_entry_new().
33 <!-- ##### SECTION ./tmpl/desktop_entry.sgml:See_Also ##### -->
39 <!-- ##### SECTION ./tmpl/desktop_entry.sgml:Short_Description ##### -->
40 serializes and deserializes a desktop entry.
43 <!-- ##### SECTION ./tmpl/desktop_entry.sgml:Title ##### -->
47 <!-- ##### SECTION ./tmpl/glib-unused.sgml:Stability_Level ##### -->
51 <!-- ##### ENUM GChannelError ##### -->
56 @G_CHANNEL_ERROR_ACCES:
57 @G_CHANNEL_ERROR_BADF:
58 @G_CHANNEL_ERROR_DEADLK:
59 @G_CHANNEL_ERROR_FAULT:
60 @G_CHANNEL_ERROR_INVAL:
62 @G_CHANNEL_ERROR_ISDIR:
63 @G_CHANNEL_ERROR_MFILE:
64 @G_CHANNEL_ERROR_NOLCK:
65 @G_CHANNEL_ERROR_NOSPC:
66 @G_CHANNEL_ERROR_PERM:
67 @G_CHANNEL_ERROR_PIPE:
68 @G_CHANNEL_ERROR_SPIPE:
69 @G_CHANNEL_ERROR_ENCODE_RW:
70 @G_CHANNEL_ERROR_FAILED:
72 <!-- ##### ENUM GChannelStatus ##### -->
77 @G_CHANNEL_STATUS_NORMAL:
78 @G_CHANNEL_STATUS_EOF:
79 @G_CHANNEL_STATUS_PARTIAL_CHARS:
80 @G_CHANNEL_STATUS_AGAIN:
81 @G_CHANNEL_STATUS_INTR:
82 @G_CHANNEL_STATUS_ERROR:
83 @G_CHANNEL_STATUS_BAD_INPUT:
85 <!-- ##### USER_FUNCTION GCompareFuncData ##### -->
95 <!-- ##### USER_FUNCTION GCompletionStrcmpFunc ##### -->
104 <!-- ##### STRUCT GDesktopEntry ##### -->
110 <!-- ##### ENUM GDesktopEntryError ##### -->
112 Error codes returned by desktop entry parsing.
115 @G_DESKTOP_ENTRY_ERROR_UNKNOWN_ENCODING: text being parsed is not UTF-8 and
117 @G_DESKTOP_ENTRY_ERROR_BAD_START_GROUP: desktop entry does not start with a
119 @G_DESKTOP_ENTRY_ERROR_PARSE: desktop entry is empty or contains invalid
121 @G_DESKTOP_ENTRY_ERROR_NOT_FOUND: valid desktop entry could not be found.
122 @G_DESKTOP_ENTRY_ERROR_KEY_NOT_FOUND: desktop entry does not have requested
124 @G_DESKTOP_ENTRY_ERROR_GROUP_NOT_FOUND: desktop entry does not have requested
126 @G_DESKTOP_ENTRY_ERROR_INVALID_VALUE: desktop entry contains key which has
127 value that cannot be validated.
129 <!-- ##### ENUM GDesktopEntryFlags ##### -->
131 #GDesktopEntry supports a few flags for tweaking performance during
132 deserialization. #G_DESKTOP_ENTRY_DISCARD_COMMENTS and
133 #G_DESKTOP_ENTRY_DISCARD_TRANSLATIONS will reduce memory footprint,
134 and #G_DESKTOP_ENTRY_GENERATE_LOOKUP_MAP will increase key lookup speed.
137 @G_DESKTOP_ENTRY_NONE: use parser defaults
138 @G_DESKTOP_ENTRY_DISCARD_COMMENTS: Discard all lines that are blank
140 @G_DESKTOP_ENTRY_DISCARD_TRANSLATIONS: Only retain translations that
141 are returned by g_get_language_names().
142 @G_DESKTOP_ENTRY_GENERATE_LOOKUP_MAP: Generate a lookup map for key names to make lookups constant time at the cost of more memory.
144 <!-- ##### USER_FUNCTION GErrorFunc ##### -->
146 Specifies the type of function passed to g_set_error_handler().
149 @str: the error message.
151 <!-- ##### USER_FUNCTION GHookFreeFunc ##### -->
159 <!-- ##### ENUM GIOFileMode ##### -->
164 @G_IO_FILE_MODE_READ:
165 @G_IO_FILE_MODE_WRITE:
166 @G_IO_FILE_MODE_APPEND:
167 @G_IO_FILE_MODE_READ_WRITE:
168 @G_IO_FILE_MODE_READ_WRITE_TRUNCATE:
169 @G_IO_FILE_MODE_READ_WRITE_APPEND:
171 <!-- ##### ENUM GMatchType ##### -->
173 Enumeration representing different kinds of patterns. This is only used
174 internally for optimizing the match algorithm.
177 @G_MATCH_ALL: a general pattern.
178 @G_MATCH_ALL_TAIL: a general pattern which contains a fixed part matching
179 the end of the string.
180 @G_MATCH_HEAD: a pattern matching every string with a certain prefix.
181 @G_MATCH_TAIL: a pattern matching every string with a certain suffix.
182 @G_MATCH_EXACT: a pattern matching exactly one string.
185 <!-- ##### USER_FUNCTION GWarningFunc ##### -->
187 Specifies the type of function passed to g_set_warning_handler().
190 @str: the warning message.
192 <!-- ##### MACRO G_CHANNEL_ERROR ##### -->
198 <!-- ##### MACRO G_DESKTOP_ENTRY_ERROR ##### -->
200 Error domain for desktop entry parsing. Errors in this domain will
201 be from the #GDesktopEntryError enumeration. See #GError for information on
206 <!-- ##### MACRO G_HOOK_DEFERRED_DESTROY ##### -->
212 <!-- ##### MACRO G_IO_CHANNEL_DEFAULT_LINE_TERM ##### -->
214 One of %G_IO_CHANNEL_UNIX_LINE_TERM, %G_IO_CHANNEL_DOS_LINE_TERM,
215 or %G_IO_CHANNEL_MACINTOSH_LINE_TERM (unimplemented)
216 depending on the system type.
220 <!-- ##### MACRO G_IO_CHANNEL_DOS_LINE_TERM ##### -->
226 <!-- ##### MACRO G_IO_CHANNEL_ENCODE_RAW ##### -->
228 Encoding for nonbuffered IO. With this encoding, data must be
229 read using g_io_channel_read_chars(); the other functions will
234 <!-- ##### MACRO G_IO_CHANNEL_MACINTOSH_LINE_TERM ##### -->
240 <!-- ##### MACRO G_IO_CHANNEL_UNIX_LINE_TERM ##### -->
246 <!-- ##### MACRO NAME_MAX ##### -->
248 Provided for UNIX emulation on Windows; equivalent to UNIX macro
249 %NAME_MAX, which is the maximum length of a single path component.
250 i.e. just the <filename>foo</filename> in <filename>/usr/bin/foo</filename>.
254 <!-- ##### MACRO access ##### -->
260 <!-- ##### MACRO close ##### -->
266 <!-- ##### FUNCTION closedir ##### -->
268 Provided for UNIX emulation on Windows; see documentation for <function>closedir()</function>
275 <!-- ##### MACRO fdopen ##### -->
281 <!-- ##### MACRO ftruncate ##### -->
283 Provided for UNIX emulation on Windows; see documentation for ftruncate()
290 <!-- ##### FUNCTION g_channel_error_from_errno ##### -->
298 <!-- ##### FUNCTION g_channel_error_quark ##### -->
305 <!-- ##### FUNCTION g_convert_error_quark ##### -->
312 <!-- ##### FUNCTION g_desktop_entry_escape_strings ##### -->
320 <!-- ##### FUNCTION g_desktop_entry_free ##### -->
327 <!-- ##### FUNCTION g_desktop_entry_get_boolean ##### -->
338 <!-- ##### FUNCTION g_desktop_entry_get_boolean_list ##### -->
350 <!-- ##### FUNCTION g_desktop_entry_get_groups ##### -->
359 <!-- ##### FUNCTION g_desktop_entry_get_integer ##### -->
370 <!-- ##### FUNCTION g_desktop_entry_get_integer_list ##### -->
382 <!-- ##### FUNCTION g_desktop_entry_get_keys ##### -->
393 <!-- ##### FUNCTION g_desktop_entry_get_locale_string ##### -->
405 <!-- ##### FUNCTION g_desktop_entry_get_locale_string_list ##### -->
418 <!-- ##### FUNCTION g_desktop_entry_get_start_group ##### -->
426 <!-- ##### FUNCTION g_desktop_entry_get_string ##### -->
437 <!-- ##### FUNCTION g_desktop_entry_get_string_list ##### -->
449 <!-- ##### FUNCTION g_desktop_entry_has_group ##### -->
458 <!-- ##### FUNCTION g_desktop_entry_has_key ##### -->
469 <!-- ##### FUNCTION g_desktop_entry_new ##### -->
478 <!-- ##### FUNCTION g_desktop_entry_new_from_data ##### -->
490 <!-- ##### FUNCTION g_desktop_entry_new_from_data_dirs ##### -->
502 <!-- ##### FUNCTION g_desktop_entry_new_from_file ##### -->
513 <!-- ##### FUNCTION g_desktop_entry_remove_group ##### -->
522 <!-- ##### FUNCTION g_desktop_entry_remove_key ##### -->
532 <!-- ##### FUNCTION g_desktop_entry_set_boolean ##### -->
543 <!-- ##### FUNCTION g_desktop_entry_set_boolean_list ##### -->
555 <!-- ##### FUNCTION g_desktop_entry_set_integer ##### -->
566 <!-- ##### FUNCTION g_desktop_entry_set_integer_list ##### -->
578 <!-- ##### FUNCTION g_desktop_entry_set_locale_string ##### -->
590 <!-- ##### FUNCTION g_desktop_entry_set_locale_string_list ##### -->
603 <!-- ##### FUNCTION g_desktop_entry_set_string ##### -->
614 <!-- ##### FUNCTION g_desktop_entry_set_string_list ##### -->
626 <!-- ##### FUNCTION g_desktop_entry_to_data ##### -->
636 <!-- ##### FUNCTION g_file_replace ##### -->
647 <!-- ##### FUNCTION g_io_channel_error_quark ##### -->
654 <!-- ##### VARIABLE g_log_domain_glib ##### -->
656 The log domain used for messages logged by GLib itself.
660 <!-- ##### FUNCTION g_main_add_poll ##### -->
662 Adds a file descriptor to be polled.
663 This is usually combined with g_source_add() to add an event source.
664 The event source's check function will typically test the revents
665 field in the #GPollFD struct and return TRUE if events need to be processed.
668 @fd: a #GPollFD, which is a file descriptor together with a bitwise
669 combination of #GIOCondition flags determining which events to poll for.
670 @priority: the priority of the poll, which should be the same as the priority
671 used for g_source_add() to ensure that the file descriptor is polled whenever
672 the results may be needed.
673 See #G_PRIORITY_DEFAULT, #G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH,
674 #G_PRIORITY_HIGH_IDLE, and #G_PRIORITY_LOW.
676 <!-- ##### FUNCTION g_main_context_get ##### -->
684 <!-- ##### FUNCTION g_main_loop_destroy ##### -->
691 <!-- ##### FUNCTION g_main_remove_poll ##### -->
693 Removes a file descriptor from the list being polled.
696 @fd: the #GPollFD to remove.
698 <!-- ##### FUNCTION g_main_win32_get_poll_func ##### -->
705 <!-- ##### FUNCTION g_mem_check ##### -->
707 Checks if the given memory has already been freed. If it has it outputs
709 To use this function you must configure glib with the flag
710 '--enable-mem-check=yes' before compiling.
713 @mem: the memory to check.
715 <!-- ##### FUNCTION g_regex_error_quark ##### -->
722 <!-- ##### FUNCTION g_scanner_stat_mode ##### -->
724 Gets the file attributes.
725 This is the <structfield>st_mode</structfield> field from the
726 <structname>stat</structname> structure. See the <function>stat()</function>
730 @filename: the file name.
731 @Returns: the file attributes.
733 <!-- ##### FUNCTION g_set_error_handler ##### -->
735 Sets the function to be called to handle error messages.
736 This function is deprecated in favour of the new logging facilities.
739 @func: the function to be called to handle error messages.
740 @Returns: the old error handler.
742 <!-- ##### FUNCTION g_set_message_handler ##### -->
744 Sets the function to be called to handle messages.
745 This function is deprecated in favour of the new logging facilities.
748 @func: the function to be called to handle normal messages.
749 @Returns: the old message handler.
751 <!-- ##### FUNCTION g_set_warning_handler ##### -->
753 Sets the function to be called to handle warning messages.
754 This function is deprecated in favour of the new logging facilities.
757 @func: the function to be called to handle warning messages.
758 @Returns: the old warning handler.
760 <!-- ##### FUNCTION g_source_add ##### -->
774 <!-- ##### FUNCTION g_source_connect ##### -->
784 <!-- ##### FUNCTION g_source_connect_indirect ##### -->
793 <!-- ##### FUNCTION g_source_remove_by_source_data ##### -->
795 Removes the first event source found with the given source data.
798 Event sources are sorted with the highest priority first. Sources with equal
799 priority are stored in the order in which they were added.
802 @source_data: the source data, which contains information specific to the
804 @Returns: TRUE if an event source was found and removed.
806 <!-- ##### FUNCTION g_static_private_get_for_thread ##### -->
815 <!-- ##### FUNCTION g_static_private_set_for_thread ##### -->
825 <!-- ##### MACRO g_string ##### -->
827 Turns the argument into a string literal by using the '#' stringizing operator.
830 @x: text to convert to a literal string.
832 <!-- ##### MACRO getcwd ##### -->
838 <!-- ##### MACRO getpid ##### -->
844 <!-- ##### MACRO lseek ##### -->
850 <!-- ##### MACRO open ##### -->
856 <!-- ##### FUNCTION opendir ##### -->
858 Provided for UNIX emulation on Windows; see documentation for <function>opendir()</function>
865 <!-- ##### MACRO pclose ##### -->
871 <!-- ##### MACRO pipe ##### -->
873 Provided for UNIX emulation on Windows; see documentation for pipe()
877 @phandles: file descriptors, the first one for reading, the second one for writing.
879 <!-- ##### MACRO popen ##### -->
885 <!-- ##### MACRO read ##### -->
891 <!-- ##### MACRO readdir ##### -->
893 Provided for UNIX emulation on Windows; see documentation for <function>readdir()</function>
898 <!-- ##### FUNCTION rewinddir ##### -->
900 Provided for UNIX emulation on Windows; see documentation for <function>rewinddir()</function>
906 <!-- ##### MACRO write ##### -->