1 files changed, 113 insertions, 0 deletions
diff --git a/include/yasl/desktop.h b/include/yasl/desktop.h
new file mode 100644
index 0000000..3e72a50
--- /dev/null
+++ b/include/yasl/desktop.h
@@ -0,0 +1,113 @@
+/**
+ * @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.
+ */
+#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);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* YASL_DESKTOP_H */