416 lines
14 KiB
C++
416 lines
14 KiB
C++
#pragma once
|
|
|
|
#ifdef __cplusplus
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
extern "C" {
|
|
#else
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
#endif
|
|
|
|
#define YAMS_MOBILE_API_VERSION_MAJOR 1U
|
|
#define YAMS_MOBILE_API_VERSION_MINOR 0U
|
|
#define YAMS_MOBILE_API_VERSION_PATCH 0U
|
|
|
|
#define YAMS_MOBILE_MAKE_VERSION(major, minor, patch) \
|
|
((((uint32_t)(major)) << 16U) | (((uint32_t)(minor)) << 8U) | ((uint32_t)(patch)))
|
|
|
|
#define YAMS_MOBILE_API_VERSION \
|
|
YAMS_MOBILE_MAKE_VERSION(YAMS_MOBILE_API_VERSION_MAJOR, YAMS_MOBILE_API_VERSION_MINOR, \
|
|
YAMS_MOBILE_API_VERSION_PATCH)
|
|
|
|
#ifndef YAMS_MOBILE_API
|
|
#if defined(_WIN32) && !defined(YAMS_STATIC)
|
|
#ifdef yams_mobile_EXPORTS
|
|
#define YAMS_MOBILE_API __declspec(dllexport)
|
|
#else
|
|
#define YAMS_MOBILE_API __declspec(dllimport)
|
|
#endif
|
|
#else
|
|
#define YAMS_MOBILE_API __attribute__((visibility("default")))
|
|
#endif
|
|
#endif
|
|
|
|
/**
|
|
* ABI version for mobile bindings. Increment MAJOR on breaking changes.
|
|
*/
|
|
typedef struct yams_mobile_version_info {
|
|
uint16_t major;
|
|
uint16_t minor;
|
|
uint16_t patch;
|
|
} yams_mobile_version_info;
|
|
|
|
/**
|
|
* Status codes returned by the mobile bindings.
|
|
*/
|
|
typedef enum yams_mobile_status {
|
|
YAMS_MOBILE_STATUS_OK = 0,
|
|
YAMS_MOBILE_STATUS_INVALID_ARGUMENT = 1,
|
|
YAMS_MOBILE_STATUS_NOT_INITIALIZED = 2,
|
|
YAMS_MOBILE_STATUS_INTERNAL_ERROR = 3,
|
|
YAMS_MOBILE_STATUS_TIMEOUT = 4,
|
|
YAMS_MOBILE_STATUS_UNAVAILABLE = 5,
|
|
YAMS_MOBILE_STATUS_NOT_FOUND = 6,
|
|
YAMS_MOBILE_STATUS_UNKNOWN = 255
|
|
} yams_mobile_status;
|
|
|
|
/**
|
|
* Opaque context handle representing a configured search/grep environment.
|
|
*/
|
|
typedef struct yams_mobile_context_t yams_mobile_context_t;
|
|
|
|
typedef enum yams_mobile_backend_mode {
|
|
YAMS_MOBILE_BACKEND_EMBEDDED = 0,
|
|
YAMS_MOBILE_BACKEND_DAEMON = 1
|
|
} yams_mobile_backend_mode;
|
|
|
|
typedef struct yams_mobile_context_config {
|
|
uint32_t struct_size; /**< Size of this struct for forward compatibility (set to sizeof). */
|
|
uint32_t version; /**< Packed API version from `YAMS_MOBILE_API_VERSION`. */
|
|
uint32_t reserved; /**< Reserved for future use; set to 0. */
|
|
const char* working_directory; /**< Root path for metadata/storage; UTF-8, nullable */
|
|
const char* cache_directory; /**< Optional cache directory override */
|
|
const char* telemetry_sink; /**< Optional sink identifier ("console", "stderr", "noop", or
|
|
"file:/path") */
|
|
uint32_t max_worker_threads; /**< 0 => auto */
|
|
uint32_t flags; /**< Reserved for future feature toggles */
|
|
uint32_t backend_mode; /**< 0 => embedded (default), 1 => daemon */
|
|
const char* daemon_socket_path; /**< Optional daemon socket override when backend_mode=daemon */
|
|
} yams_mobile_context_config;
|
|
|
|
/**
|
|
* Basic request envelope shared by grep and search flows.
|
|
*/
|
|
typedef struct yams_mobile_request_header {
|
|
uint32_t struct_size; /**< Size of this struct (set to sizeof). */
|
|
uint32_t version; /**< Packed API version from `YAMS_MOBILE_API_VERSION`. */
|
|
uint32_t flags; /**< Reserved flags for request-specific toggles; set to 0. */
|
|
const char* correlation_id; /**< Optional identifier for tracing */
|
|
uint32_t timeout_ms; /**< 0 => default */
|
|
} yams_mobile_request_header;
|
|
|
|
/**
|
|
* Represents a UTF-8 string slice owned by the callee.
|
|
*/
|
|
typedef struct yams_mobile_string_view {
|
|
const char* data;
|
|
size_t length;
|
|
} yams_mobile_string_view;
|
|
|
|
/**
|
|
* Grep parameters (subset of CLI options).
|
|
*/
|
|
typedef struct yams_mobile_grep_request {
|
|
yams_mobile_request_header header;
|
|
const char* pattern;
|
|
uint8_t literal;
|
|
uint8_t ignore_case;
|
|
uint8_t word_boundary;
|
|
uint32_t max_matches;
|
|
} yams_mobile_grep_request;
|
|
|
|
/**
|
|
* Grep result handle; caller must dispose via `yams_mobile_grep_result_destroy`.
|
|
*/
|
|
typedef struct yams_mobile_grep_result_t yams_mobile_grep_result_t;
|
|
|
|
/**
|
|
* Search parameters (hybrid/semantic options to be expanded).
|
|
*/
|
|
typedef struct yams_mobile_search_request {
|
|
yams_mobile_request_header header;
|
|
const char* query;
|
|
uint32_t limit;
|
|
const char** tags;
|
|
size_t tag_count;
|
|
uint8_t paths_only;
|
|
uint8_t semantic;
|
|
} yams_mobile_search_request;
|
|
|
|
typedef struct yams_mobile_search_result_t yams_mobile_search_result_t;
|
|
|
|
typedef struct yams_mobile_document_store_request {
|
|
yams_mobile_request_header header;
|
|
const char* path;
|
|
const char** tags;
|
|
size_t tag_count;
|
|
uint8_t sync_now;
|
|
} yams_mobile_document_store_request;
|
|
|
|
typedef struct yams_mobile_download_request {
|
|
yams_mobile_request_header header;
|
|
const char* url;
|
|
const char** tags;
|
|
size_t tag_count;
|
|
const char** metadata_keys;
|
|
const char** metadata_values;
|
|
size_t metadata_count;
|
|
uint32_t timeout_ms;
|
|
uint8_t overwrite;
|
|
} yams_mobile_download_request;
|
|
|
|
typedef struct yams_mobile_metadata_request {
|
|
yams_mobile_request_header header;
|
|
const char* document_hash;
|
|
const char* path;
|
|
} yams_mobile_metadata_request;
|
|
|
|
typedef struct yams_mobile_metadata_result_t yams_mobile_metadata_result_t;
|
|
|
|
typedef struct yams_mobile_vector_status_request {
|
|
yams_mobile_request_header header;
|
|
/* Deprecated no-op retained for ABI compatibility. */
|
|
uint8_t warmup;
|
|
} yams_mobile_vector_status_request;
|
|
|
|
typedef struct yams_mobile_vector_status_result_t yams_mobile_vector_status_result_t;
|
|
|
|
typedef struct yams_mobile_list_request {
|
|
yams_mobile_request_header header;
|
|
const char* pattern;
|
|
const char** tags;
|
|
size_t tag_count;
|
|
uint32_t limit;
|
|
uint32_t offset;
|
|
uint8_t match_all_tags;
|
|
uint8_t paths_only;
|
|
} yams_mobile_list_request;
|
|
|
|
typedef struct yams_mobile_list_result_t yams_mobile_list_result_t;
|
|
|
|
typedef struct yams_mobile_update_request {
|
|
yams_mobile_request_header header;
|
|
const char* hash;
|
|
const char* name;
|
|
const char** add_tags;
|
|
size_t add_tag_count;
|
|
const char** remove_tags;
|
|
size_t remove_tag_count;
|
|
const char** metadata_keys;
|
|
const char** metadata_values;
|
|
size_t metadata_count;
|
|
} yams_mobile_update_request;
|
|
|
|
typedef struct yams_mobile_update_result_t yams_mobile_update_result_t;
|
|
|
|
typedef struct yams_mobile_delete_request {
|
|
yams_mobile_request_header header;
|
|
const char* hash;
|
|
const char* name;
|
|
const char* pattern;
|
|
uint8_t dry_run;
|
|
} yams_mobile_delete_request;
|
|
|
|
typedef struct yams_mobile_delete_result_t yams_mobile_delete_result_t;
|
|
|
|
typedef struct yams_mobile_graph_query_request {
|
|
yams_mobile_request_header header;
|
|
const char* document_hash;
|
|
const char* document_name;
|
|
const char* snapshot_id;
|
|
int64_t node_id;
|
|
const char** relation_filters;
|
|
size_t relation_filter_count;
|
|
int32_t max_depth;
|
|
uint32_t max_results;
|
|
uint32_t offset;
|
|
uint32_t limit;
|
|
uint8_t reverse_traversal;
|
|
uint8_t include_edge_properties;
|
|
uint8_t include_node_properties;
|
|
} yams_mobile_graph_query_request;
|
|
|
|
typedef struct yams_mobile_graph_query_result_t yams_mobile_graph_query_result_t;
|
|
|
|
typedef struct yams_mobile_document_get_request {
|
|
yams_mobile_request_header header;
|
|
const char* document_hash;
|
|
const char* name;
|
|
uint8_t metadata_only;
|
|
uint8_t include_content;
|
|
uint8_t include_extracted_text;
|
|
uint8_t raw;
|
|
uint8_t latest;
|
|
uint8_t oldest;
|
|
uint64_t max_bytes;
|
|
} yams_mobile_document_get_request;
|
|
|
|
typedef struct yams_mobile_document_get_result_t yams_mobile_document_get_result_t;
|
|
|
|
/**
|
|
* Retrieve the compiled ABI version.
|
|
*/
|
|
YAMS_MOBILE_API yams_mobile_version_info yams_mobile_get_version(void);
|
|
|
|
/**
|
|
* Create/destroy the shared mobile context.
|
|
*/
|
|
YAMS_MOBILE_API yams_mobile_status yams_mobile_context_create(
|
|
const yams_mobile_context_config* config, yams_mobile_context_t** out_context);
|
|
|
|
YAMS_MOBILE_API void yams_mobile_context_destroy(yams_mobile_context_t* ctx);
|
|
|
|
/**
|
|
* Execute grep/search operations. Results require explicit destroy calls.
|
|
*/
|
|
YAMS_MOBILE_API yams_mobile_status yams_mobile_grep_execute(yams_mobile_context_t* ctx,
|
|
const yams_mobile_grep_request* request,
|
|
yams_mobile_grep_result_t** out_result);
|
|
|
|
YAMS_MOBILE_API void yams_mobile_grep_result_destroy(yams_mobile_grep_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status
|
|
yams_mobile_search_execute(yams_mobile_context_t* ctx, const yams_mobile_search_request* request,
|
|
yams_mobile_search_result_t** out_result);
|
|
|
|
YAMS_MOBILE_API void yams_mobile_search_result_destroy(yams_mobile_search_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status yams_mobile_store_document(
|
|
yams_mobile_context_t* ctx, const yams_mobile_document_store_request* request,
|
|
yams_mobile_string_view* out_hash);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status yams_mobile_download(yams_mobile_context_t* ctx,
|
|
const yams_mobile_download_request* request,
|
|
yams_mobile_string_view* out_hash);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status
|
|
yams_mobile_update_document(yams_mobile_context_t* ctx, const yams_mobile_update_request* request,
|
|
yams_mobile_update_result_t** out_result);
|
|
|
|
YAMS_MOBILE_API void yams_mobile_update_result_destroy(yams_mobile_update_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_update_result_json(const yams_mobile_update_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status
|
|
yams_mobile_delete_by_name(yams_mobile_context_t* ctx, const yams_mobile_delete_request* request,
|
|
yams_mobile_delete_result_t** out_result);
|
|
|
|
YAMS_MOBILE_API void yams_mobile_delete_result_destroy(yams_mobile_delete_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_delete_result_json(const yams_mobile_delete_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status
|
|
yams_mobile_graph_query(yams_mobile_context_t* ctx, const yams_mobile_graph_query_request* request,
|
|
yams_mobile_graph_query_result_t** out_result);
|
|
|
|
YAMS_MOBILE_API void
|
|
yams_mobile_graph_query_result_destroy(yams_mobile_graph_query_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_graph_query_result_json(const yams_mobile_graph_query_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status yams_mobile_remove_document(yams_mobile_context_t* ctx,
|
|
const char* document_hash);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status
|
|
yams_mobile_get_metadata(yams_mobile_context_t* ctx, const yams_mobile_metadata_request* request,
|
|
yams_mobile_metadata_result_t** out_result);
|
|
|
|
YAMS_MOBILE_API void yams_mobile_metadata_result_destroy(yams_mobile_metadata_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status yams_mobile_get_vector_status(
|
|
yams_mobile_context_t* ctx, const yams_mobile_vector_status_request* request,
|
|
yams_mobile_vector_status_result_t** out_result);
|
|
|
|
YAMS_MOBILE_API void
|
|
yams_mobile_vector_status_result_destroy(yams_mobile_vector_status_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_metadata_result_json(const yams_mobile_metadata_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_vector_status_result_json(const yams_mobile_vector_status_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_grep_result_stats_json(const yams_mobile_grep_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_search_result_stats_json(const yams_mobile_search_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_search_result_json(const yams_mobile_search_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_grep_result_json(const yams_mobile_grep_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status
|
|
yams_mobile_list_documents(yams_mobile_context_t* ctx, const yams_mobile_list_request* request,
|
|
yams_mobile_list_result_t** out_result);
|
|
|
|
YAMS_MOBILE_API void yams_mobile_list_result_destroy(yams_mobile_list_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_list_result_json(const yams_mobile_list_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_status yams_mobile_get_document(
|
|
yams_mobile_context_t* ctx, const yams_mobile_document_get_request* request,
|
|
yams_mobile_document_get_result_t** out_result);
|
|
|
|
YAMS_MOBILE_API void
|
|
yams_mobile_document_get_result_destroy(yams_mobile_document_get_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_document_get_result_json(const yams_mobile_document_get_result_t* result);
|
|
|
|
YAMS_MOBILE_API yams_mobile_string_view
|
|
yams_mobile_document_get_result_content(const yams_mobile_document_get_result_t* result);
|
|
|
|
/**
|
|
* Fetch extended error information for the last API call on the invoking thread.
|
|
* Returns a pointer valid until the next API invocation on the same thread.
|
|
*/
|
|
YAMS_MOBILE_API const char* yams_mobile_last_error_message(void);
|
|
|
|
#ifdef __cplusplus
|
|
} // extern "C"
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
static inline yams_mobile_context_config yams_mobile_context_config_default() {
|
|
yams_mobile_context_config config{};
|
|
config.struct_size = sizeof(yams_mobile_context_config);
|
|
config.version = YAMS_MOBILE_API_VERSION;
|
|
config.reserved = 0U;
|
|
config.backend_mode = YAMS_MOBILE_BACKEND_EMBEDDED;
|
|
config.daemon_socket_path = nullptr;
|
|
return config;
|
|
}
|
|
|
|
static inline yams_mobile_request_header yams_mobile_request_header_default() {
|
|
yams_mobile_request_header header{};
|
|
header.struct_size = sizeof(yams_mobile_request_header);
|
|
header.version = YAMS_MOBILE_API_VERSION;
|
|
header.flags = 0U;
|
|
header.correlation_id = nullptr;
|
|
header.timeout_ms = 0U;
|
|
return header;
|
|
}
|
|
#else
|
|
static inline yams_mobile_context_config yams_mobile_context_config_default(void) {
|
|
yams_mobile_context_config config;
|
|
config.struct_size = sizeof(yams_mobile_context_config);
|
|
config.version = YAMS_MOBILE_API_VERSION;
|
|
config.reserved = 0U;
|
|
config.working_directory = NULL;
|
|
config.cache_directory = NULL;
|
|
config.telemetry_sink = NULL;
|
|
config.max_worker_threads = 0U;
|
|
config.flags = 0U;
|
|
config.backend_mode = YAMS_MOBILE_BACKEND_EMBEDDED;
|
|
config.daemon_socket_path = NULL;
|
|
return config;
|
|
}
|
|
|
|
static inline yams_mobile_request_header yams_mobile_request_header_default(void) {
|
|
yams_mobile_request_header header;
|
|
header.struct_size = sizeof(yams_mobile_request_header);
|
|
header.version = YAMS_MOBILE_API_VERSION;
|
|
header.flags = 0U;
|
|
header.correlation_id = NULL;
|
|
header.timeout_ms = 0U;
|
|
return header;
|
|
}
|
|
#endif
|