sqlite_objs_sys/
lib.rs

1//! Raw FFI bindings to the sqlite-objs C library.
2//!
3//! This crate provides low-level unsafe bindings to the sqlite-objs VFS.
4//! Most users should use the `sqlite-objs` crate instead, which provides
5//! a safe, idiomatic Rust API.
6
7#![allow(non_camel_case_types)]
8
9use libc::{c_char, c_int, c_void};
10
11/// Opaque type for Azure operations vtable (defined in azure_client.h)
12#[repr(C)]
13pub struct azure_ops_t {
14    _private: [u8; 0],
15}
16
17/// Configuration for the sqlite-objs VFS.
18///
19/// This struct maps directly to the C `sqlite_objs_config_t` type.
20#[repr(C)]
21#[derive(Debug)]
22pub struct sqlite_objs_config_t {
23    /// Azure Storage account name
24    pub account: *const c_char,
25    /// Blob container name
26    pub container: *const c_char,
27    /// SAS token (preferred), or NULL
28    pub sas_token: *const c_char,
29    /// Shared Key (fallback), or NULL
30    pub account_key: *const c_char,
31    /// Optional custom endpoint (for Azurite), or NULL for Azure
32    pub endpoint: *const c_char,
33    /// Optional: override the Azure operations vtable
34    pub ops: *const azure_ops_t,
35    /// Opaque context pointer passed to ops functions
36    pub ops_ctx: *mut c_void,
37}
38
39extern "C" {
40    /// Register the "sqlite-objs" VFS.
41    ///
42    /// Reads configuration from environment variables:
43    /// - AZURE_STORAGE_ACCOUNT
44    /// - AZURE_STORAGE_CONTAINER
45    /// - AZURE_STORAGE_SAS (checked first)
46    /// - AZURE_STORAGE_KEY (fallback)
47    ///
48    /// If `makeDefault` is non-zero, this VFS becomes the default.
49    /// Returns SQLITE_OK (0) on success, or an appropriate error code.
50    pub fn sqlite_objs_vfs_register(makeDefault: c_int) -> c_int;
51
52    /// Register the "sqlite-objs" VFS with an explicit configuration.
53    ///
54    /// The config struct is copied — the caller may free it after this call.
55    /// If `makeDefault` is non-zero, this VFS becomes the default.
56    /// Returns SQLITE_OK (0) on success, or an appropriate error code.
57    pub fn sqlite_objs_vfs_register_with_config(
58        config: *const sqlite_objs_config_t,
59        makeDefault: c_int,
60    ) -> c_int;
61
62    /// Register the "sqlite-objs" VFS with an explicit ops vtable and context.
63    ///
64    /// Convenience wrapper for test code.
65    pub fn sqlite_objs_vfs_register_with_ops(
66        ops: *mut azure_ops_t,
67        ctx: *mut c_void,
68        makeDefault: c_int,
69    ) -> c_int;
70
71    /// Register the "sqlite-objs" VFS with no global Azure client.
72    ///
73    /// All databases MUST provide Azure credentials via URI parameters:
74    /// `file:mydb.db?azure_account=acct&azure_container=cont&azure_sas=token`
75    ///
76    /// Supported URI parameters:
77    /// - azure_account (required)
78    /// - azure_container
79    /// - azure_sas
80    /// - azure_key
81    /// - azure_endpoint
82    ///
83    /// If `makeDefault` is non-zero, this VFS becomes the default.
84    /// Returns SQLITE_OK (0) on success, or an appropriate error code.
85    pub fn sqlite_objs_vfs_register_uri(makeDefault: c_int) -> c_int;
86}
87
88// SQLite constants
89pub const SQLITE_OK: c_int = 0;
90pub const SQLITE_ERROR: c_int = 1;
91pub const SQLITE_CANTOPEN: c_int = 14;
92pub const SQLITE_NOMEM: c_int = 7;
93
94#[cfg(test)]
95mod tests {
96    use super::*;
97
98    #[test]
99    fn test_config_size() {
100        // Ensure the struct layout matches C expectations
101        assert!(std::mem::size_of::<sqlite_objs_config_t>() > 0);
102    }
103
104    #[test]
105    fn test_register_uri() {
106        // Test that we can call the FFI function (registration will fail
107        // without Azure config, but linkage should work)
108        unsafe {
109            let result = sqlite_objs_vfs_register_uri(0);
110            // Should return SQLITE_OK since URI mode doesn't require config upfront
111            assert_eq!(result, SQLITE_OK);
112        }
113    }
114}
sqlite_objs_sys/lib.rs

sqlite_objs_sys/
lib.rs
