1 files changed, 12 insertions, 104 deletions
diff --git a/include/yasl/desktop.h b/include/yasl/desktop.h
index 3e72a50..2c2379e 100644
--- a/include/yasl/desktop.h
+++ b/include/yasl/desktop.h
@@ -1,113 +1,21 @@
-/**
- * @file
- * Desktop services next to windowing: opening URIs, notifications, the bell,
- * appearance preferences, and process paths.
- *
- * Display and surface functions use the display's opening thread (the main
- * thread on Cocoa). Path and locale functions may be called from any thread.
- * On Linux, notifications and appearance use the D-Bus session bus when YASL
- * is built with libdbus-1; without it they report unsupported.
- *
- * Functions that fill a buffer return the full string length in bytes,
- * excluding the NUL, or zero on failure. A result less than cap means out
- * holds the NUL-terminated string. Otherwise out is unchanged; call again with
- * a buffer of at least the result plus one.
- */
+/** @file Optional desktop services; window operations use the owning thread. */
 #ifndef YASL_DESKTOP_H
 #define YASL_DESKTOP_H
-
 #include "yasl/yasl.h"
-
 #ifdef __cplusplus
 extern "C" {
 #endif
-
-/** Appearance preference flags returned by yasl_display_appearance(). */
-enum yasl_appearance : uint32_t {
-    YASL_APPEARANCE_DARK          = 1 << 0, /**< The user prefers dark colors. */
-    YASL_APPEARANCE_LIGHT         = 1 << 1, /**< The user prefers light colors. */
-    YASL_APPEARANCE_HIGH_CONTRAST = 1 << 2, /**< The user asks for higher contrast. */
-};
-
-/**
- * Open a URI with the user's default handler.
- * @param d Display, or NULL.
- * @param uri NUL-terminated absolute URI with a scheme, such as https: or file:.
- * @return true if the request was handed to the system; false for NULL
- * arguments, a missing scheme, or a failed launch.
- * YASL checks only the URI syntax. The application decides which schemes and
- * hosts it trusts. Success does not confirm that a handler opened the URI.
- * Linux runs xdg-open from PATH in a new session, with default signal
- * dispositions, an empty signal mask, stdin on /dev/null, and no descriptors
- * above stderr. It forks a short-lived helper first, which raises SIGCHLD;
- * YASL reaps it unless the application's reaper does. Cocoa uses NSWorkspace.
- */
-YASL_API bool yasl_display_open_uri(struct yasl_display *d, const char *uri);
-/**
- * Show a desktop notification.
- * @param d Display, or NULL.
- * @param title NUL-terminated UTF-8 summary.
- * @param body NUL-terminated UTF-8 body, or NULL for none.
- * @return true if the request was sent; false for NULL arguments or when no
- * notification service is available.
- * Linux sends org.freedesktop.Notifications.Notify with the display's app_id
- * as the application name and desktop-entry hint. Cocoa uses the user
- * notification center, which needs an app bundle with a bundle identifier,
- * and asks for permission on first use. Success does not confirm that the
- * notification was shown.
- */
-YASL_API bool yasl_display_notify(struct yasl_display *d, const char *title, const char *body);
-/**
- * Read the user's appearance preferences.
- * @param d Display, or NULL.
- * @return A yasl_appearance bitmask, or zero for NULL, no preference, or no
- * way to read it.
- * Linux reads color-scheme and contrast from the XDG Settings portal, which
- * waits briefly for a reply, then falls back to the GTK_THEME variable. Cocoa
- * reads the effective appearance and the increase-contrast setting. The
- * result is not cached and no change notification is sent; query again when
- * the window is focused.
- */
-YASL_API uint32_t yasl_display_appearance(struct yasl_display *d);
-/**
- * Ring the system bell for a surface.
- * @param s Surface, or NULL.
- * @return true if the request was sent; false for NULL or when unsupported.
- * The system decides whether the bell is audible, visual, or muted. Wayland
- * needs the xdg-system-bell protocol; X11 uses the XKB bell for the window
- * and Cocoa uses NSBeep.
- */
-YASL_API bool yasl_surface_bell(struct yasl_surface *s);
-/**
- * Get the absolute path of the running executable, with symbolic links resolved.
- * @param out Output buffer, or NULL when cap is zero.
- * @param cap Size of out in bytes.
- * @return Path length, or zero on failure. See the buffer rule in this file.
- */
-YASL_API size_t yasl_executable_path(char *out, size_t cap);
-/**
- * Get the resource directory of the app bundle that contains the executable.
- * @param out Output buffer, or NULL when cap is zero.
- * @param cap Size of out in bytes.
- * @return Path length, or zero when the executable is not in an app bundle.
- * Only Cocoa has app bundles; other platforms return zero.
- */
-YASL_API size_t yasl_resource_dir(char *out, size_t cap);
-/**
- * Get the user's preferred locale as a POSIX locale name, such as "en_US.UTF-8".
- * @param out Output buffer, or NULL when cap is zero.
- * @param cap Size of out in bytes.
- * @return Name length, or zero on failure.
- * Linux returns the first nonempty LC_ALL, LC_CTYPE, or LANG, and "C.UTF-8"
- * when none is set. Cocoa builds the name from the current locale's language
- * and region with a ".UTF-8" codeset, because apps started from Finder have no
- * locale variables. Use the result to set LANG for child processes; YASL does
- * not change the process locale.
- */
-YASL_API size_t yasl_default_locale(char *out, size_t cap);
-
+enum yasl_appearance { YASL_APPEARANCE_DARK=1u, YASL_APPEARANCE_LIGHT=2u, YASL_APPEARANCE_HIGH_CONTRAST=4u };
+YASL_API bool yasl_open_uri(const char *uri);
+YASL_API bool yasl_notify(const char *title, const char *body);
+YASL_API unsigned yasl_appearance(void);
+YASL_API bool yasl_surface_bell(yasl_surface *surface);
+/** Full byte length excluding NUL, zero on failure. Buffer unchanged unless cap
+ * exceeds returned length. NULL/zero queries size. These three are thread-safe. */
+YASL_API size_t yasl_executable_path(char *out, size_t capacity);
+YASL_API size_t yasl_resource_dir(char *out, size_t capacity);
+YASL_API size_t yasl_default_locale(char *out, size_t capacity);
 #ifdef __cplusplus
 }
 #endif
-
-#endif /* YASL_DESKTOP_H */
+#endif