Add initial vkm.h

vkm/vkm.h

@@ -0,0 +1,89 @@
+/*
+ * Virtual keyboard/mouse interface
+ *
+ * Copyright (C) 2026 Nirenjan Krishnan (nirenjan@nirenjan.org)
+ *
+ * SPDX-License-Identifier: GPL-2.0-only WITH Classpath-exception-2.0
+ */
+
+/**
+ * @file vkm.h
+ * @brief Functions, structures and enumerations for the virtual
+ * keyboard/mouse interface library (VKM).
+ *
+ * This file contains the type, enum and function prototypes for VKM.
+ * These functions allow an application to inject keyboard/mouse events
+ * into the host OS, as long as it has the necessary permissions.
+ *
+ * @author Nirenjan Krishnan (nirenjan@nirenjan.org)
+ */
+#ifndef VKM_H
+#define VKM_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Opaque structure used by the VKM framework
+ */
+struct vkm_context;
+
+/**
+ * @brief Virtual device context structure used by the VKM framework
+ *
+ * All VKM API functions require the application to pass in a pointer to
+ * a valid context structure. A pointer can be obtained by calling
+ * \ref vkm_init
+ */
+typedef struct vkm_context vkm_context;
+
+/**
+ * @brief Return type used by VKM API functions
+ */
+typedef int32_t vkm_result;
+
+/**
+ * @brief Initialize the VKM library
+ *
+ * This function initializes the VKM library, sets up any internal data
+ * structures to send input events, and returns a \ref vkm_context pointer
+ * in the output parameter. All calls to VKM use the returned pointer to
+ * inject keyboard/mouse events.
+ *
+ * @par Example
+ * @code
+ * vkm_result rc;
+ * vkm_context *ctx;
+ * rc = vkm_init(&ctx);
+ * if (rc != LIBX52_SUCCESS) {
+ *     // Error handling omitted for brevity
+ * }
+ * // Save ctx for use later
+ * @endcode
+ *
+ * @param[out]  ctx     Pointer to a \ref vkm_context *. This function will
+ * allocate a context and return the pointer to the context in this variable.
+ *
+ * @returns \ref vkm_error_code indicating status
+ */
+vkm_result vkm_init(vkm_context **ctx);
+
+/**
+ * @brief Exit the VKM library and free up any resources used
+ *
+ * This function releases any resources allocated by \ref vkm_init and
+ * terminates the library. Using the freed context now is invalid and can
+ * cause errors
+ *
+ * @param[in]   ctx     Context pointer
+ */
+void vkm_exit(vkm_context *ctx);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // !defined VKM_H