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 <!-- ##### SECTION ./tmpl/limits.sgml.sgml:Image ##### -->
55 <!-- ##### SECTION ./tmpl/limits.sgml.sgml:Long_Description ##### -->
61 <!-- ##### SECTION ./tmpl/limits.sgml.sgml:See_Also ##### -->
67 <!-- ##### SECTION ./tmpl/limits.sgml.sgml:Short_Description ##### -->
71 <!-- ##### SECTION ./tmpl/limits.sgml.sgml:Stability_Level ##### -->
75 <!-- ##### SECTION ./tmpl/limits.sgml.sgml:Title ##### -->
79 <!-- ##### SECTION ./tmpl/testutils.sgml:Long_Description ##### -->
85 <!-- ##### SECTION ./tmpl/testutils.sgml:See_Also ##### -->
91 <!-- ##### SECTION ./tmpl/testutils.sgml:Short_Description ##### -->
95 <!-- ##### SECTION ./tmpl/testutils.sgml:Stability_Level ##### -->
99 <!-- ##### SECTION ./tmpl/testutils.sgml:Title ##### -->
103 <!-- ##### ENUM GChannelError ##### -->
108 @G_CHANNEL_ERROR_ACCES:
109 @G_CHANNEL_ERROR_BADF:
110 @G_CHANNEL_ERROR_DEADLK:
111 @G_CHANNEL_ERROR_FAULT:
112 @G_CHANNEL_ERROR_INVAL:
114 @G_CHANNEL_ERROR_ISDIR:
115 @G_CHANNEL_ERROR_MFILE:
116 @G_CHANNEL_ERROR_NOLCK:
117 @G_CHANNEL_ERROR_NOSPC:
118 @G_CHANNEL_ERROR_PERM:
119 @G_CHANNEL_ERROR_PIPE:
120 @G_CHANNEL_ERROR_SPIPE:
121 @G_CHANNEL_ERROR_ENCODE_RW:
122 @G_CHANNEL_ERROR_FAILED:
124 <!-- ##### ENUM GChannelStatus ##### -->
129 @G_CHANNEL_STATUS_NORMAL:
130 @G_CHANNEL_STATUS_EOF:
131 @G_CHANNEL_STATUS_PARTIAL_CHARS:
132 @G_CHANNEL_STATUS_AGAIN:
133 @G_CHANNEL_STATUS_INTR:
134 @G_CHANNEL_STATUS_ERROR:
135 @G_CHANNEL_STATUS_BAD_INPUT:
137 <!-- ##### USER_FUNCTION GCompareFuncData ##### -->
147 <!-- ##### USER_FUNCTION GCompletionStrcmpFunc ##### -->
156 <!-- ##### STRUCT GDesktopEntry ##### -->
162 <!-- ##### ENUM GDesktopEntryError ##### -->
164 Error codes returned by desktop entry parsing.
167 @G_DESKTOP_ENTRY_ERROR_UNKNOWN_ENCODING: text being parsed is not UTF-8 and
169 @G_DESKTOP_ENTRY_ERROR_BAD_START_GROUP: desktop entry does not start with a
171 @G_DESKTOP_ENTRY_ERROR_PARSE: desktop entry is empty or contains invalid
173 @G_DESKTOP_ENTRY_ERROR_NOT_FOUND: valid desktop entry could not be found.
174 @G_DESKTOP_ENTRY_ERROR_KEY_NOT_FOUND: desktop entry does not have requested
176 @G_DESKTOP_ENTRY_ERROR_GROUP_NOT_FOUND: desktop entry does not have requested
178 @G_DESKTOP_ENTRY_ERROR_INVALID_VALUE: desktop entry contains key which has
179 value that cannot be validated.
181 <!-- ##### ENUM GDesktopEntryFlags ##### -->
183 #GDesktopEntry supports a few flags for tweaking performance during
184 deserialization. #G_DESKTOP_ENTRY_DISCARD_COMMENTS and
185 #G_DESKTOP_ENTRY_DISCARD_TRANSLATIONS will reduce memory footprint,
186 and #G_DESKTOP_ENTRY_GENERATE_LOOKUP_MAP will increase key lookup speed.
189 @G_DESKTOP_ENTRY_NONE: use parser defaults
190 @G_DESKTOP_ENTRY_DISCARD_COMMENTS: Discard all lines that are blank
192 @G_DESKTOP_ENTRY_DISCARD_TRANSLATIONS: Only retain translations that
193 are returned by g_get_language_names().
194 @G_DESKTOP_ENTRY_GENERATE_LOOKUP_MAP: Generate a lookup map for key names to make lookups constant time at the cost of more memory.
196 <!-- ##### USER_FUNCTION GErrorFunc ##### -->
198 Specifies the type of function passed to g_set_error_handler().
201 @str: the error message.
203 <!-- ##### USER_FUNCTION GHookFreeFunc ##### -->
211 <!-- ##### ENUM GIOFileMode ##### -->
216 @G_IO_FILE_MODE_READ:
217 @G_IO_FILE_MODE_WRITE:
218 @G_IO_FILE_MODE_APPEND:
219 @G_IO_FILE_MODE_READ_WRITE:
220 @G_IO_FILE_MODE_READ_WRITE_TRUNCATE:
221 @G_IO_FILE_MODE_READ_WRITE_APPEND:
223 <!-- ##### ENUM GMatchType ##### -->
225 Enumeration representing different kinds of patterns. This is only used
226 internally for optimizing the match algorithm.
229 @G_MATCH_ALL: a general pattern.
230 @G_MATCH_ALL_TAIL: a general pattern which contains a fixed part matching
231 the end of the string.
232 @G_MATCH_HEAD: a pattern matching every string with a certain prefix.
233 @G_MATCH_TAIL: a pattern matching every string with a certain suffix.
234 @G_MATCH_EXACT: a pattern matching exactly one string.
237 <!-- ##### USER_FUNCTION GWarningFunc ##### -->
239 Specifies the type of function passed to g_set_warning_handler().
242 @str: the warning message.
244 <!-- ##### MACRO G_CHANNEL_ERROR ##### -->
250 <!-- ##### MACRO G_DESKTOP_ENTRY_ERROR ##### -->
252 Error domain for desktop entry parsing. Errors in this domain will
253 be from the #GDesktopEntryError enumeration. See #GError for information on
258 <!-- ##### MACRO G_HOOK_DEFERRED_DESTROY ##### -->
264 <!-- ##### MACRO G_IO_CHANNEL_DEFAULT_LINE_TERM ##### -->
266 One of %G_IO_CHANNEL_UNIX_LINE_TERM, %G_IO_CHANNEL_DOS_LINE_TERM,
267 or %G_IO_CHANNEL_MACINTOSH_LINE_TERM (unimplemented)
268 depending on the system type.
272 <!-- ##### MACRO G_IO_CHANNEL_DOS_LINE_TERM ##### -->
278 <!-- ##### MACRO G_IO_CHANNEL_ENCODE_RAW ##### -->
280 Encoding for nonbuffered IO. With this encoding, data must be
281 read using g_io_channel_read_chars(); the other functions will
286 <!-- ##### MACRO G_IO_CHANNEL_MACINTOSH_LINE_TERM ##### -->
292 <!-- ##### MACRO G_IO_CHANNEL_UNIX_LINE_TERM ##### -->
298 <!-- ##### MACRO NAME_MAX ##### -->
300 Provided for UNIX emulation on Windows; equivalent to UNIX macro
301 %NAME_MAX, which is the maximum length of a single path component.
302 i.e. just the <filename>foo</filename> in <filename>/usr/bin/foo</filename>.
306 <!-- ##### MACRO access ##### -->
312 <!-- ##### MACRO close ##### -->
318 <!-- ##### FUNCTION closedir ##### -->
320 Provided for UNIX emulation on Windows; see documentation for <function>closedir()</function>
327 <!-- ##### MACRO fdopen ##### -->
333 <!-- ##### MACRO ftruncate ##### -->
335 Provided for UNIX emulation on Windows; see documentation for ftruncate()
342 <!-- ##### FUNCTION g_channel_error_from_errno ##### -->
350 <!-- ##### FUNCTION g_channel_error_quark ##### -->
357 <!-- ##### FUNCTION g_convert_error_quark ##### -->
364 <!-- ##### FUNCTION g_desktop_entry_escape_strings ##### -->
372 <!-- ##### FUNCTION g_desktop_entry_free ##### -->
379 <!-- ##### FUNCTION g_desktop_entry_get_boolean ##### -->
390 <!-- ##### FUNCTION g_desktop_entry_get_boolean_list ##### -->
402 <!-- ##### FUNCTION g_desktop_entry_get_groups ##### -->
411 <!-- ##### FUNCTION g_desktop_entry_get_integer ##### -->
422 <!-- ##### FUNCTION g_desktop_entry_get_integer_list ##### -->
434 <!-- ##### FUNCTION g_desktop_entry_get_keys ##### -->
445 <!-- ##### FUNCTION g_desktop_entry_get_locale_string ##### -->
457 <!-- ##### FUNCTION g_desktop_entry_get_locale_string_list ##### -->
470 <!-- ##### FUNCTION g_desktop_entry_get_start_group ##### -->
478 <!-- ##### FUNCTION g_desktop_entry_get_string ##### -->
489 <!-- ##### FUNCTION g_desktop_entry_get_string_list ##### -->
501 <!-- ##### FUNCTION g_desktop_entry_has_group ##### -->
510 <!-- ##### FUNCTION g_desktop_entry_has_key ##### -->
521 <!-- ##### FUNCTION g_desktop_entry_new ##### -->
530 <!-- ##### FUNCTION g_desktop_entry_new_from_data ##### -->
542 <!-- ##### FUNCTION g_desktop_entry_new_from_data_dirs ##### -->
554 <!-- ##### FUNCTION g_desktop_entry_new_from_file ##### -->
565 <!-- ##### FUNCTION g_desktop_entry_remove_group ##### -->
574 <!-- ##### FUNCTION g_desktop_entry_remove_key ##### -->
584 <!-- ##### FUNCTION g_desktop_entry_set_boolean ##### -->
595 <!-- ##### FUNCTION g_desktop_entry_set_boolean_list ##### -->
607 <!-- ##### FUNCTION g_desktop_entry_set_integer ##### -->
618 <!-- ##### FUNCTION g_desktop_entry_set_integer_list ##### -->
630 <!-- ##### FUNCTION g_desktop_entry_set_locale_string ##### -->
642 <!-- ##### FUNCTION g_desktop_entry_set_locale_string_list ##### -->
655 <!-- ##### FUNCTION g_desktop_entry_set_string ##### -->
666 <!-- ##### FUNCTION g_desktop_entry_set_string_list ##### -->
678 <!-- ##### FUNCTION g_desktop_entry_to_data ##### -->
688 <!-- ##### FUNCTION g_file_replace ##### -->
699 <!-- ##### FUNCTION g_format_file_size_for_display ##### -->
707 <!-- ##### FUNCTION g_io_channel_error_quark ##### -->
714 <!-- ##### VARIABLE g_log_domain_glib ##### -->
716 The log domain used for messages logged by GLib itself.
720 <!-- ##### FUNCTION g_main_add_poll ##### -->
722 Adds a file descriptor to be polled.
723 This is usually combined with g_source_add() to add an event source.
724 The event source's check function will typically test the revents
725 field in the #GPollFD struct and return TRUE if events need to be processed.
728 @fd: a #GPollFD, which is a file descriptor together with a bitwise
729 combination of #GIOCondition flags determining which events to poll for.
730 @priority: the priority of the poll, which should be the same as the priority
731 used for g_source_add() to ensure that the file descriptor is polled whenever
732 the results may be needed.
733 See #G_PRIORITY_DEFAULT, #G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH,
734 #G_PRIORITY_HIGH_IDLE, and #G_PRIORITY_LOW.
736 <!-- ##### FUNCTION g_main_context_get ##### -->
744 <!-- ##### FUNCTION g_main_loop_destroy ##### -->
751 <!-- ##### FUNCTION g_main_remove_poll ##### -->
753 Removes a file descriptor from the list being polled.
756 @fd: the #GPollFD to remove.
758 <!-- ##### FUNCTION g_main_win32_get_poll_func ##### -->
765 <!-- ##### FUNCTION g_mem_check ##### -->
767 Checks if the given memory has already been freed. If it has it outputs
769 To use this function you must configure glib with the flag
770 '--enable-mem-check=yes' before compiling.
773 @mem: the memory to check.
775 <!-- ##### FUNCTION g_regex_error_quark ##### -->
782 <!-- ##### FUNCTION g_regex_free ##### -->
789 <!-- ##### FUNCTION g_scanner_stat_mode ##### -->
791 Gets the file attributes.
792 This is the <structfield>st_mode</structfield> field from the
793 <structname>stat</structname> structure. See the <function>stat()</function>
797 @filename: the file name.
798 @Returns: the file attributes.
800 <!-- ##### FUNCTION g_set_error_handler ##### -->
802 Sets the function to be called to handle error messages.
803 This function is deprecated in favour of the new logging facilities.
806 @func: the function to be called to handle error messages.
807 @Returns: the old error handler.
809 <!-- ##### FUNCTION g_set_message_handler ##### -->
811 Sets the function to be called to handle messages.
812 This function is deprecated in favour of the new logging facilities.
815 @func: the function to be called to handle normal messages.
816 @Returns: the old message handler.
818 <!-- ##### FUNCTION g_set_warning_handler ##### -->
820 Sets the function to be called to handle warning messages.
821 This function is deprecated in favour of the new logging facilities.
824 @func: the function to be called to handle warning messages.
825 @Returns: the old warning handler.
827 <!-- ##### FUNCTION g_source_add ##### -->
841 <!-- ##### FUNCTION g_source_connect ##### -->
851 <!-- ##### FUNCTION g_source_connect_indirect ##### -->
860 <!-- ##### FUNCTION g_source_remove_by_source_data ##### -->
862 Removes the first event source found with the given source data.
865 Event sources are sorted with the highest priority first. Sources with equal
866 priority are stored in the order in which they were added.
869 @source_data: the source data, which contains information specific to the
871 @Returns: TRUE if an event source was found and removed.
873 <!-- ##### FUNCTION g_static_private_get_for_thread ##### -->
882 <!-- ##### FUNCTION g_static_private_set_for_thread ##### -->
892 <!-- ##### MACRO g_string ##### -->
894 Turns the argument into a string literal by using the '#' stringizing operator.
897 @x: text to convert to a literal string.
899 <!-- ##### FUNCTION g_variant_get_byte_array ##### -->
908 <!-- ##### FUNCTION g_variant_new_byte_array ##### -->
917 <!-- ##### FUNCTION g_warn_message ##### -->
928 <!-- ##### MACRO getcwd ##### -->
934 <!-- ##### MACRO getpid ##### -->
940 <!-- ##### MACRO lseek ##### -->
946 <!-- ##### MACRO open ##### -->
952 <!-- ##### FUNCTION opendir ##### -->
954 Provided for UNIX emulation on Windows; see documentation for <function>opendir()</function>
961 <!-- ##### MACRO pclose ##### -->
967 <!-- ##### MACRO pipe ##### -->
969 Provided for UNIX emulation on Windows; see documentation for pipe()
973 @phandles: file descriptors, the first one for reading, the second one for writing.
975 <!-- ##### MACRO popen ##### -->
981 <!-- ##### MACRO read ##### -->
987 <!-- ##### MACRO readdir ##### -->
989 Provided for UNIX emulation on Windows; see documentation for <function>readdir()</function>
994 <!-- ##### FUNCTION rewinddir ##### -->
996 Provided for UNIX emulation on Windows; see documentation for <function>rewinddir()</function>
1002 <!-- ##### MACRO write ##### -->