vmette 0.3.0

/*
 * vmette.h — C ABI for the vmette local sandbox library.
 *
 * Generated by cbindgen from crates/vmette/src/ffi.rs. Do not edit by hand;
 * re-run `make header` (cargo build -p vmette --features regenerate-header).
 */

#ifndef VMETTE_H
#define VMETTE_H

#pragma once

/* WARNING: this file is auto-generated. Edits will be lost. */

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

/**
 * Status codes returned by C-ABI functions.
 */
enum VmetteStatus {
  Ok = 0,
  InvalidConfig = 1,
  StartFailed = 2,
  RestoreFailed = 3,
  SaveFailed = 4,
  SnapshotUnsupported = 5,
  Timeout = 6,
  Vsock = 7,
  Io = 8,
  NullArg = 9,
  InvalidUtf8 = 10,
};
typedef int32_t VmetteStatus;

/**
 * Opaque handle to a [`Config`].
 */
typedef struct vmette_config_t {
  uint8_t _private[0];
} vmette_config_t;

/**
 * Opaque handle to a [`RunOutput`].
 */
typedef struct vmette_run_output_t {
  uint8_t _private[0];
} vmette_run_output_t;

/**
 * Construct a new config with the minimum required fields. Returns NULL
 * on null arguments or invalid UTF-8.
 *
 * # Safety
 * See the module-level safety contract.
 */
 struct vmette_config_t *vmette_config_new(const char *kernel, const char *initramfs);

/**
 * Free a config. No-op on NULL.
 *
 * # Safety
 * See the module-level safety contract. After this call `cfg` is dangling
 * and must not be reused.
 */
 void vmette_config_free(struct vmette_config_t *cfg);

/**
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_cmdline(struct vmette_config_t *cfg, const char *cmdline);

/**
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_rootfs_share(struct vmette_config_t *cfg, const char *path, bool read_only);

/**
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_add_share(struct vmette_config_t *cfg, const char *tag, const char *path);

/**
 * Append a `KEY=value` environment variable applied in the guest before the
 * exec command (overrides any OCI image env). Ignored on null/invalid-UTF-8
 * args.
 *
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_add_env(struct vmette_config_t *cfg, const char *key, const char *value);

/**
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_add_disk(struct vmette_config_t *cfg, const char *path);

/**
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_exec(struct vmette_config_t *cfg, const char *cmd);

/**
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_net(struct vmette_config_t *cfg, bool enable);

/**
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_switch_root(struct vmette_config_t *cfg, bool enable);

/**
 * Set the vsock port policy.
 * `port < 0`  → disable the vsock device entirely.
 * `port == 0` → auto-allocate per invocation (50000..60000).
 * `port > 0`  → use that exact port.
 *
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_vsock_port(struct vmette_config_t *cfg, int32_t port);

/**
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_guest_vsock_port(struct vmette_config_t *cfg, uint32_t port);

/**
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_timeout(struct vmette_config_t *cfg, uint32_t seconds);

/**
 * Note: no clamping. A value VZ rejects (e.g. 0) surfaces as
 * `InvalidConfig` from `vmette_run` — same path as the Rust API.
 *
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_vcpus(struct vmette_config_t *cfg, uint8_t n);

/**
 * Note: no clamping. See `vmette_config_set_vcpus` for the rationale.
 *
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_mem_mib(struct vmette_config_t *cfg, uint64_t n);

/**
 * Path to a snapshot file to write after the guest signals ready.
 * Apple Silicon only — see VmetteStatus::SnapshotUnsupported.
 *
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_build_snapshot(struct vmette_config_t *cfg, const char *path);

/**
 * Path to a previously-saved snapshot to restore. Apple Silicon only.
 *
 * # Safety
 * See the module-level safety contract.
 */
 void vmette_config_set_resume_snapshot(struct vmette_config_t *cfg, const char *path);

/**
 * Run a configured guest. Blocks until the guest powers off.
 *
 * On success returns [`VmetteStatus::Ok`] and writes a newly-allocated
 * run output handle to `*out` (caller must `vmette_run_output_free`).
 * On error returns the matching status and leaves `*out` untouched.
 *
 * Note: in the common path this function never returns — the underlying
 * `vmette::run` exits the process via the VM's lifecycle delegate with
 * the guest's exit code.
 *
 * # Safety
 * See the module-level safety contract. `out` must be a valid, writable
 * pointer to a `*mut vmette_run_output_t`.
 */
 VmetteStatus vmette_run(const struct vmette_config_t *cfg, struct vmette_run_output_t **out);

/**
 * # Safety
 * See the module-level safety contract.
 */
 int32_t vmette_run_output_exit_code(const struct vmette_run_output_t *out);

/**
 * # Safety
 * See the module-level safety contract. After this call `out` is dangling
 * and must not be reused.
 */
 void vmette_run_output_free(struct vmette_run_output_t *out);

/**
 * Returns the library's semver string (e.g. "0.1.0"). Caller must not free.
 */
 const char *vmette_version(void);

#endif  /* VMETTE_H */