nt-lite/code/public/ntlite/desktop.h

// Native desktop/window protocol and client helpers. DWM owns window policy while RSSRV retains Session 0 routing authority.

#pragma once

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <ntlite/display.h>
#include <ntlite/handle.h>
#include <ntlite/input.h>
#include <ntlite/status.h>

#define NTL_DESKTOP_PROTOCOL_VERSION 2u
#define NTL_DESKTOP_SERVICE_PATH "/Sessions/0/Desktop"

#define NTL_DESKTOP_FLAG_NONE 0x00000000u

#define NTL_DESKTOP_OP_CREATE_WINDOW       1u
#define NTL_DESKTOP_OP_DESTROY_WINDOW      2u
#define NTL_DESKTOP_OP_SET_BOUNDS          3u
#define NTL_DESKTOP_OP_SET_VISIBLE         4u
#define NTL_DESKTOP_OP_RAISE_WINDOW        5u
#define NTL_DESKTOP_OP_LOWER_WINDOW        6u
#define NTL_DESKTOP_OP_REQUEST_FOCUS       7u
#define NTL_DESKTOP_OP_REQUEST_CAPTURE     8u
#define NTL_DESKTOP_OP_RELEASE_CAPTURE     9u
#define NTL_DESKTOP_OP_SET_POINTER_MODE   10u
#define NTL_DESKTOP_OP_ATTACH_SURFACE     11u
#define NTL_DESKTOP_OP_DETACH_SURFACE     12u
#define NTL_DESKTOP_OP_QUERY_WINDOW       13u

#define NTL_DESKTOP_EVENT_KEY   1u
#define NTL_DESKTOP_EVENT_MOUSE 2u

#define NTL_DESKTOP_POINTER_FREE            0u
#define NTL_DESKTOP_POINTER_CONFINED        1u
#define NTL_DESKTOP_POINTER_RELATIVE_LOCKED 2u

typedef uint64_t NTL_WINDOW_ID;

// One fixed desktop request. ATTACH_SURFACE carries exactly one surface capability.
typedef struct NTL_DESKTOP_REQUEST {
    uint32_t Size;
    uint32_t Version;
    uint32_t Operation;
    uint32_t Flags;
    NTL_WINDOW_ID WindowId;
    DISPLAY_RECT Bounds;
    uint32_t Value;
    uint32_t Reserved;
} NTL_DESKTOP_REQUEST;

// One fixed desktop reply. Query fields are meaningful after CREATE_WINDOW or QUERY_WINDOW.
typedef struct NTL_DESKTOP_REPLY {
    uint32_t Size;
    uint32_t Version;
    uint32_t Operation;
    uint32_t Flags;
    KSTATUS Status;
    uint32_t Reserved;
    NTL_WINDOW_ID WindowId;
    DISPLAY_RECT Bounds;
    bool Visible;
    bool Focused;
    bool Captured;
    bool HasSurface;
    uint32_t SurfaceWidth;
    uint32_t SurfaceHeight;
} NTL_DESKTOP_REPLY;

// One asynchronous input notification delivered to the owning window connection.
typedef struct NTL_DESKTOP_EVENT {
    uint32_t Size;
    uint32_t Version;
    uint32_t Type;
    uint32_t Flags;
    NTL_WINDOW_ID WindowId;
    int32_t PointerX;
    int32_t PointerY;
    INPUT_KEY_RECORD Key;
    INPUT_MOUSE_EVENT Mouse;
} NTL_DESKTOP_EVENT;

// DWM and clients exchange these versioned fixed-layout protocol messages.
_Static_assert(sizeof(NTL_DESKTOP_REQUEST) == 48u, "NTL_DESKTOP_REQUEST ABI size changed");
_Static_assert(offsetof(NTL_DESKTOP_REQUEST, WindowId) == 16u, "NTL_DESKTOP_REQUEST window offset changed");
_Static_assert(offsetof(NTL_DESKTOP_REPLY, Visible) == 48u, "NTL_DESKTOP_REPLY Visible offset changed");
_Static_assert(offsetof(NTL_DESKTOP_REPLY, SurfaceWidth) == 52u, "NTL_DESKTOP_REPLY SurfaceWidth offset changed");
_Static_assert(sizeof(NTL_DESKTOP_REPLY) == 64u, "NTL_DESKTOP_REPLY ABI size changed");
_Static_assert(offsetof(NTL_DESKTOP_REPLY, Status) == 16u, "NTL_DESKTOP_REPLY status offset changed");
_Static_assert(sizeof(NTL_DESKTOP_EVENT) == 56u, "NTL_DESKTOP_EVENT ABI size changed");
_Static_assert(offsetof(NTL_DESKTOP_EVENT, Key) == 32u, "NTL_DESKTOP_EVENT key offset changed");

#if defined(NTL_SYSCALL_STATIC)
#define NTL_DESKTOP_API
#elif defined(NTL_SYSCALL_BUILD)
#define NTL_DESKTOP_API __declspec(dllexport)
#else
#define NTL_DESKTOP_API
#endif

// Connects to the active Session 0 desktop endpoint through RSSRV.
NTL_DESKTOP_API KSTATUS NtlDesktopConnect(SYS_HANDLE* sessionOut);

// Creates one hidden client-owned top-level window.
NTL_DESKTOP_API KSTATUS NtlDesktopCreateWindow(SYS_HANDLE session, const DISPLAY_RECT* bounds, NTL_WINDOW_ID* windowOut);

// Destroys one window owned by this connection.
NTL_DESKTOP_API KSTATUS NtlDesktopDestroyWindow(SYS_HANDLE session, NTL_WINDOW_ID window);

// Changes one window's screen-space bounds.
NTL_DESKTOP_API KSTATUS NtlDesktopSetBounds(SYS_HANDLE session, NTL_WINDOW_ID window, const DISPLAY_RECT* bounds);

// Shows or hides one window without changing its z-order.
NTL_DESKTOP_API KSTATUS NtlDesktopSetVisible(SYS_HANDLE session, NTL_WINDOW_ID window, bool visible);

// Moves one window to the top of the z-order.
NTL_DESKTOP_API KSTATUS NtlDesktopRaiseWindow(SYS_HANDLE session, NTL_WINDOW_ID window);

// Moves one window to the bottom of the z-order.
NTL_DESKTOP_API KSTATUS NtlDesktopLowerWindow(SYS_HANDLE session, NTL_WINDOW_ID window);

// Requests Session 0 keyboard focus for one visible window.
NTL_DESKTOP_API KSTATUS NtlDesktopRequestFocus(SYS_HANDLE session, NTL_WINDOW_ID window);

// Requests Session 0 pointer capture for one visible window.
NTL_DESKTOP_API KSTATUS NtlDesktopRequestCapture(SYS_HANDLE session, NTL_WINDOW_ID window);

// Releases pointer capture only when this window currently owns it.
NTL_DESKTOP_API KSTATUS NtlDesktopReleaseCapture(SYS_HANDLE session, NTL_WINDOW_ID window);

// Sets visible cursor policy for the focused/captured window.
NTL_DESKTOP_API KSTATUS NtlDesktopSetPointerMode(SYS_HANDLE session, NTL_WINDOW_ID window, uint32_t mode);

// Attaches a shared surface. DWM receives only QUERY, WAIT, and MAP_READ rights.
NTL_DESKTOP_API KSTATUS NtlDesktopAttachSurface(SYS_HANDLE session, NTL_WINDOW_ID window, SYS_HANDLE surface);

// Detaches the current shared surface from one window.
NTL_DESKTOP_API KSTATUS NtlDesktopDetachSurface(SYS_HANDLE session, NTL_WINDOW_ID window);

// Queries one connection-owned window.
NTL_DESKTOP_API KSTATUS NtlDesktopQueryWindow(SYS_HANDLE session, NTL_WINDOW_ID window, NTL_DESKTOP_REPLY* replyOut);

// Receives one asynchronous key or mouse event from DWM.
NTL_DESKTOP_API KSTATUS NtlDesktopReceiveEvent(SYS_HANDLE session, uint64_t timeoutMilliseconds, NTL_DESKTOP_EVENT* eventOut);

// Disconnects and closes one desktop session endpoint.
NTL_DESKTOP_API KSTATUS NtlDesktopClose(SYS_HANDLE session);

#undef NTL_DESKTOP_API